[Libguestfs] [PATCH] New API: mdadm-stop for stopping MD devices.

[Richard W.M. Jones]

On Wed, Nov 23, 2011 at 10:47:57PM +0800, Wanlong Gao wrote:
> This API is used to stop a md device.
> When we want to move a device to another md array, we should
> stop the md device which contained this device first.
[...]
> +  ("mdadm_stop", (RErr, [Device "md"], []), 302, [],

This needs to be conditional on mdadm support, so change this to:

 ("mdadm_stop", (RErr, [Device "md"], []), 302, [Optional "mdadm"],

(compare it with mdadm_create).

> +This command is a wrap of 'mdadm --stop md'.
> +Use this command to stop a created Linux md (RAID) device.
> +
> +NOTE: This just stop the md device but not remove or zeroed it.");

This description needs improvement: It's better not to say that the
command is equivalent to some other command (mdadm) that we have no
control over, since if mdadm changes then the API described here
effectively changes.

Also, you can (and should) use POD mark-up (see perlpod man page).

Therefore I would change this to something like:

  This command deactivates the MD array named C<md>.  The
  device is stopped, but it is not destroyed or zeroed.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming blog: http://rwmj.wordpress.com
Fedora now supports 80 OCaml packages (the OPEN alternative to F#)
http://cocan.org/getting_started_with_ocaml_on_red_hat_and_fedora