Re: [PATCH] Add documentation to the dm and dmraid pythong bindings. As well as to the

[David Lehman <dlehman redhat com>]

On Tue, 2009-01-06 at 17:09 +0100, Joel Granados Moreno wrote:
> ---
>  __init__.py |   12 ++++++++++++
>  dm.c        |   33 +++++++++++++++++++++++++++------
>  dmraid.c    |   23 +++++++++++++++++------
>  3 files changed, 56 insertions(+), 12 deletions(-)

Looks good in general. Some typos noted below...

> 
> diff --git a/__init__.py b/__init__.py
> index 943e127..8b255c6 100644
> --- a/__init__.py
> +++ b/__init__.py
> @@ -70,6 +74,10 @@ def getDevice(name):
>              return (map.dev.major, map.dev.minor)
>  
>  def getMPaths(disks, logger=None):
> +    """Retrieve all the Multi path devices in the system.
> +
> +    Returns a list or Multi path  objects.
> +    """

a list *of* Multi path objects

>      old = disks
>      disks = []
>      for disk in old:
> @@ -157,6 +165,10 @@ def getMPaths(disks, logger=None):
>      return mpList
>  
>  def getRaidSets(*disks):
> +    """Retrieve all the raid sets in the system.
> +
> +    Returns a list or RaidSet objects.
> +    """

same as above ("list of RaidSet objects")

>      # make it so you don't have to apply() to pass a list
>      old = disks
>      disks = []
> diff --git a/dm.c b/dm.c
> index 2aa3a50..beb15ae 100644
> --- a/dm.c
> +++ b/dm.c
> @@ -1698,11 +1705,25 @@ out:
>  }
>  
>  static PyMethodDef pydm_functions[] = {
> -	{"scanparts", (PyCFunction)pydm_scan_parts, PYDM_ARGS},
> -	{"rmpart", (PyCFunction)pydm_rmpart, PYDM_ARGS},
> -	{"set_logger", (PyCFunction)pydm_log_init, PYDM_ARGS},
> -	{"maps", (PyCFunction)pydm_maps, METH_NOARGS},
> -	{"targets", (PyCFunction)pydm_targets, METH_NOARGS},
> +	{"scanparts", (PyCFunction)pydm_scan_parts, PYDM_ARGS,
> +		"Rescans the partition talbe for the specified device.  "

                                         table

> +		"Expects a string representing the device with the keyword "
> +		"dev_path. returns None on success and NULL on failure."},

                             Returns

> +	{"rmpart", (PyCFunction)pydm_rmpart, PYDM_ARGS,
> +		"Deletes a partition from the specified device.  "
> +		"Expects a string representing the device with the keyword "
> +		"dev_path and an long representing the partition number "
> +		"with the keyword partno.  Returns None on success and NULL "
> +		"on failure."},
> +	{"set_logger", (PyCFunction)pydm_log_init, PYDM_ARGS,
> +		"Defines the log function to be used.  Expects a callable "
> +		"object.  Will return None on success and NULL on failure. "},
> +	{"maps", (PyCFunction)pydm_maps, METH_NOARGS,
> +		"Scans the system for mapped devices.  It does not expect any "
> +		"arguments.  It returns a list of map objects."},
> +	{"targets", (PyCFunction)pydm_targets, METH_NOARGS,
> +		"Scans for suppoerted targets.  It does not expect any args.  "

                             supported

> +		"It returns a list of target objects."},
>  	{NULL, NULL}
>  };
>  
> diff --git a/dmraid.c b/dmraid.c
> index e693512..3100768 100644
> --- a/dmraid.c
> +++ b/dmraid.c
> @@ -265,10 +265,12 @@ pydmraid_dev_scanparts(PyObject *self, PyObject *args, PyObject *kwds)
>  static struct PyMethodDef pydmraid_dev_methods[] = {
>  	{"rmpart",
>  		(PyCFunction)pydmraid_dev_rmpart,
> -		METH_VARARGS | METH_KEYWORDS},
> +		METH_VARARGS | METH_KEYWORDS,
> +		"Removes the partition devined by the partno argument"},

                                         defined

>  	{"scanparts",
>  		(PyCFunction)pydmraid_dev_scanparts,
> -		METH_NOARGS},
> +		METH_NOARGS,
> +		"(Re)scans all partition for the current device"},

                                 partitions