commit 454723b56206234cd2903594e9354f72712c70a1
Author: Iustin Pop <iustin@google.com>
Date:   Wed Apr 14 18:45:35 2010 +0200

    Update docstrings in tools/ and enable epydoc
    
    This patch updates the docstrings in tools/ (mostly in lvmstrap, which
    is very very old code-base) and then enabled the tools in this directory
    for 'make apidoc' too.
    
    Signed-off-by: Iustin Pop <iustin@google.com>
    Reviewed-by: René Nussbaumer <rn@google.com>

diff --git a/epydoc.conf b/epydoc.conf
index 11069a3..56d471a 100644
--- a/epydoc.conf
+++ b/epydoc.conf
@@ -8,7 +8,7 @@ output: html
 # note: the wildcards means the directories should be cleaned up after each
 # run, otherwise there will be stale '*c' (compiled) files that will not be
 # parsable and will break the epydoc run
-modules: ganeti, scripts/gnt-*, daemons/ganeti-confd, daemons/ganeti-masterd, daemons/ganeti-noded, daemons/ganeti-rapi, daemons/ganeti-watcher
+modules: ganeti, scripts/gnt-*, daemons/ganeti-confd, daemons/ganeti-masterd, daemons/ganeti-noded, daemons/ganeti-rapi, daemons/ganeti-watcher, tools/*
 
 graph: all
 
diff --git a/tools/burnin b/tools/burnin
index bba3ddb..a1dfc91 100755
--- a/tools/burnin
+++ b/tools/burnin
@@ -322,7 +322,7 @@ class Burner(object):
   def _ExecOp(self, *ops):
     """Execute one or more opcodes and manage the exec buffer.
 
-    @result: if only opcode has been passed, we return its result;
+    @return: if only opcode has been passed, we return its result;
         otherwise we return the list of results
 
     """
@@ -336,7 +336,7 @@ class Burner(object):
   def ExecOp(self, retry, *ops):
     """Execute one or more opcodes and manage the exec buffer.
 
-    @result: if only opcode has been passed, we return its result;
+    @return: if only opcode has been passed, we return its result;
         otherwise we return the list of results
 
     """
@@ -892,9 +892,9 @@ class Burner(object):
     """Run confd queries for our instances.
 
     The following confd queries are tested:
-    - CONFD_REQ_PING: simple ping
-    - CONFD_REQ_CLUSTER_MASTER: cluster master
-    - CONFD_REQ_NODE_ROLE_BYNAME: node role, for the master
+      - CONFD_REQ_PING: simple ping
+      - CONFD_REQ_CLUSTER_MASTER: cluster master
+      - CONFD_REQ_NODE_ROLE_BYNAME: node role, for the master
 
     """
     Log("Checking confd results")
diff --git a/tools/cfgshell b/tools/cfgshell
index 3c53d81..77afab9 100755
--- a/tools/cfgshell
+++ b/tools/cfgshell
@@ -341,10 +341,9 @@ def ParseOptions():
   In case of command line errors, it will show the usage and exit the
   program.
 
-  Returns:
-    (options, args), as returned by OptionParser.parse_args
-  """
+  @return: a tuple (options, args), as returned by OptionParser.parse_args
 
+  """
   parser = optparse.OptionParser()
 
   options, args = parser.parse_args()
@@ -355,7 +354,6 @@ def ParseOptions():
 def main():
   """Application entry point.
 
-  This is just a wrapper over BootStrap, to handle our own exceptions.
   """
   _, args = ParseOptions()
   if args:
diff --git a/tools/cluster-merge b/tools/cluster-merge
index d82ad95..fb5e5b2 100755
--- a/tools/cluster-merge
+++ b/tools/cluster-merge
@@ -173,7 +173,7 @@ class Merger(object):
               ask_key=False):
     """Wrapping SshRunner.Run with default parameters.
 
-    For explanation of parameters see L{ssh.SshRunner.Run}.
+    For explanation of parameters see L{ganeti.ssh.SshRunner.Run}.
 
     """
     return self.ssh_runner.Run(hostname=hostname, command=command, user=user,
diff --git a/tools/lvmstrap b/tools/lvmstrap
index 01ad670..e6856c5 100755
--- a/tools/lvmstrap
+++ b/tools/lvmstrap
@@ -36,6 +36,7 @@ OSError. The idea behind this is, since we run as root, we should
 usually not get these errors, but if we do it's most probably a system
 error, so they should be handled and the user instructed to report
 them.
+
 """
 
 
@@ -66,6 +67,7 @@ class ProgrammingError(Error):
 
   This should catch sysfs tree changes, or otherwise incorrect
   assumptions about the contents of the /sys/block/... directories.
+
   """
   pass
 
@@ -79,6 +81,7 @@ class SysconfigError(Error):
 
   This should usually mean that the installation of the Xen node
   failed in some steps.
+
   """
   pass
 
@@ -92,6 +95,7 @@ class PrereqError(Error):
 
   This should usually mean that the build steps for the Xen node were
   not followed correctly.
+
   """
   pass
 
@@ -100,6 +104,7 @@ class OperationalError(Error):
   """Exception denoting actual errors.
 
   Errors during the bootstrapping are signaled using this exception.
+
   """
   pass
 
@@ -109,13 +114,15 @@ class ParameterError(Error):
 
   Wrong disks given as parameters will be signaled using this
   exception.
+
   """
   pass
 
 
 def Usage():
-  """Shows program usage information and exits the program."""
+  """Shows program usage information and exits the program.
 
+  """
   print >> sys.stderr, "Usage:"
   print >> sys.stderr, USAGE
   sys.exit(2)
@@ -127,8 +134,10 @@ def ParseOptions():
   In case of command line errors, it will show the usage and exit the
   program.
 
-  Returns:
-    (options, args), as returned by OptionParser.parse_args
+  @rtype: tuple
+  @return: a tuple of (options, args), as returned by
+      OptionParser.parse_args
+
   """
   global verbose_flag # pylint: disable-msg=W0603
 
@@ -167,13 +176,12 @@ def ExecCommand(command):
   difference that if the command line argument -v has been given, it
   will print the command line and the command output on stdout.
 
-  Args:
-    the command line
-  Returns:
-    (status, output) where status is the exit status and output the
-      stdout and stderr of the command together
-  """
+  @param command: the command line to be executed
+  @rtype: tuple
+  @return: a tuple of (status, output) where status is the exit status
+      and output the stdout and stderr of the command together
 
+  """
   if verbose_flag:
     print command
   result = RunCmd(command)
@@ -187,8 +195,8 @@ def CheckPrereq():
 
   It check that it runs on Linux 2.6, and that /sys is mounted and the
   fact that /sys/block is a directory.
-  """
 
+  """
   if os.getuid() != 0:
     raise PrereqError("This tool runs as root only. Really.")
 
@@ -220,18 +228,16 @@ def CheckPrereq():
 def CheckVGExists(vgname):
   """Checks to see if a volume group exists.
 
-  Args:
-    vgname: the volume group name
+  @param vgname: the volume group name
 
-  Returns:
-    a four-tuple (exists, lv_count, vg_size, vg_free), where:
-      exists: True if the volume exists, otherwise False; if False,
+  @return: a four-tuple (exists, lv_count, vg_size, vg_free), where:
+      - exists: True if the volume exists, otherwise False; if False,
         all other members of the tuple are None
-      lv_count: The number of logical volumes in the volume group
-      vg_size: The total size of the volume group (in gibibytes)
-      vg_free: The available space in the volume group
-  """
+      - lv_count: The number of logical volumes in the volume group
+      - vg_size: The total size of the volume group (in gibibytes)
+      - vg_free: The available space in the volume group
 
+  """
   result = ExecCommand("vgs --nohead -o lv_count,vg_size,vg_free"
                        " --nosuffix --units g"
                        " --ignorelockingfailure %s" % vgname)
@@ -261,15 +267,11 @@ def CheckSysDev(name, devnum):
   some retries here. Since we only do a stat, we can afford to do many
   short retries.
 
-  Args:
-   name: the device name, e.g. 'sda'
-   devnum: the device number, e.g. 0x803 (2051 in decimal) for sda3
+  @param name: the device name, e.g. 'sda'
+  @param devnum: the device number, e.g. 0x803 (2051 in decimal) for sda3
+  @raises L{SysconfigError}: in case of failure of the check
 
-  Returns:
-    None; failure of the check is signaled by raising a
-      SysconfigError exception
   """
-
   path = "/dev/%s" % name
   for _ in range(40):
     if os.path.exists(path):
@@ -293,13 +295,13 @@ def ReadDev(syspath):
   function reads that file and converts the major:minor pair to a dev
   number.
 
-  Args:
-    syspath: the path to a block device dir in sysfs, e.g. /sys/block/sda
+  @type syspath: string
+  @param syspath: the path to a block device dir in sysfs,
+      e.g. C{/sys/block/sda}
 
-  Returns:
-    the device number
-  """
+  @return: the device number
 
+  """
   if not os.path.exists("%s/dev" % syspath):
     raise ProgrammingError("Invalid path passed to ReadDev: %s" % syspath)
   f = open("%s/dev" % syspath)
@@ -320,11 +322,13 @@ def ReadSize(syspath):
   function reads that file and converts the number in sectors to the
   size in bytes.
 
-  Args:
-    syspath: the path to a block device dir in sysfs, e.g. /sys/block/sda
+  @type syspath: string
+  @param syspath: the path to a block device dir in sysfs,
+      e.g. C{/sys/block/sda}
+
+  @rtype: int
+  @return: the device size in bytes
 
-  Returns:
-    the device size in bytes
   """
 
   if not os.path.exists("%s/size" % syspath):
@@ -341,14 +345,13 @@ def ReadPV(name):
 
   This function tries to see if a block device is a physical volume.
 
-  Args:
-    dev: the device name (e.g. sda)
-  Returns:
-    The name of the volume group to which this PV belongs, or
-    "" if this PV is not in use, or
-    None if this is not a PV
-  """
+  @type name: string
+  @param name: the device name (e.g. sda)
+
+  @return: the name of the volume group to which this PV belongs, or
+      "" if this PV is not in use, or None if this is not a PV
 
+  """
   result = ExecCommand("pvdisplay -c /dev/%s" % name)
   if result.failed:
     return None
@@ -362,20 +365,18 @@ def GetDiskList(opts):
   This function examines the /sys/block tree and using information
   therein, computes the status of the block device.
 
-  Returns:
-    [(name, size, dev, partitions, inuse), ...]
-  where:
-    name is the block device name (e.g. sda)
-    size the size in bytes
-    dev  the device number (e.g. 8704 for hdg)
-    partitions is [(name, size, dev), ...] mirroring the disk list data
-    inuse is a boolean showing the in-use status of the disk, computed as the
-      possibility of re-reading the partition table (the meaning of the
-      operation varies with the kernel version, but is usually accurate;
-      a mounted disk/partition or swap-area or PV with active LVs on it
-      is busy)
-  """
+  @return: a list like [(name, size, dev, partitions, inuse), ...], where:
+      - name is the block device name (e.g. sda)
+      - size the size in bytes
+      - dev is the device number (e.g. 8704 for hdg)
+      - partitions is [(name, size, dev), ...] mirroring the disk list
+        data inuse is a boolean showing the in-use status of the disk,
+        computed as the possibility of re-reading the partition table
+        (the meaning of the operation varies with the kernel version,
+        but is usually accurate; a mounted disk/partition or swap-area
+        or PV with active LVs on it is busy)
 
+  """
   dlist = []
   for name in os.listdir("/sys/block"):
     if (not name.startswith("hd") and
@@ -419,10 +420,10 @@ def GetMountInfo():
   of the results is memorised for later matching against the
   /sys/block devices.
 
-  Returns:
-   a mountpoint: device number dictionary
-  """
+  @rtype: dict
+  @return: a {mountpoint: device number} dictionary
 
+  """
   mountlines = ReadFile("/proc/mounts").splitlines()
   mounts = {}
   for line in mountlines:
@@ -448,16 +449,15 @@ def GetMountInfo():
 def DevInfo(name, dev, mountinfo):
   """Computes miscellaneous information about a block device.
 
-  Args:
-    name: the device name, e.g. sda
+  @type name: string
+  @param name: the device name, e.g. sda
 
-  Returns:
-    (mpath, whatvg, fileinfo), where
-    mpath is the mount path where this device is mounted or None
-    whatvg is the result of the ReadPV function
-    fileinfo is the output of file -bs on the device
-  """
+  @return: a tuple (mpath, whatvg, fileinfo), where:
+      - mpath is the mount path where this device is mounted or None
+      - whatvg is the result of the ReadPV function
+      - fileinfo is the output of file -bs on the device
 
+  """
   if dev in mountinfo:
     mpath = mountinfo[dev]
   else:
@@ -538,10 +538,10 @@ def CheckReread(name):
   thus compute the in-use status. See the discussion in GetDiskList
   about the meaning of 'in use'.
 
-  Returns:
-    boolean, the in-use status of the device
-  """
+  @rtype: boolean
+  @return: the in-use status of the device
 
+  """
   for _ in range(3):
     result = ExecCommand("blockdev --rereadpt /dev/%s" % name)
     if not result.failed:
@@ -558,8 +558,8 @@ def WipeDisk(name):
   partition table. If not successful, it writes back the old partition
   data, and leaves the cleanup to the user.
 
-  Args:
-    the device name (e.g. sda)
+  @param name: the device name (e.g. sda)
+
   """
 
   if not CheckReread(name):
@@ -600,8 +600,8 @@ def PartitionDisk(name):
   This function creates a single partition spanning the entire disk,
   by means of fdisk.
 
-  Args:
-    the device name, e.g. sda
+  @param name: the device name, e.g. sda
+
   """
   result = ExecCommand(
     'echo ,,8e, | sfdisk /dev/%s' % name)
@@ -620,8 +620,7 @@ def CreatePVOnDisk(name):
   This function creates a physical volume on a block device, overriding
   all warnings. So it can wipe existing PVs and PVs which are in a VG.
 
-  Args:
-    the device name, e.g. sda
+  @param name: the device name, e.g. sda
 
   """
   result = ExecCommand("pvcreate -yff /dev/%s1 " % name)
@@ -638,8 +637,7 @@ def CreateVG(vgname, disks):
   This function creates a volume group named `vgname` on the disks
   given as parameters. The physical extent size is set to 64MB.
 
-  Args:
-    disks: a list of disk names, e.g. ['sda','sdb']
+  @param disks: a list of disk names, e.g. ['sda','sdb']
 
   """
   pnames = ["'/dev/%s1'" % disk for disk in disks]
@@ -659,13 +657,11 @@ def ValidateDiskList(options):
   using the --disks option) such that all given disks are present and
   not in use.
 
-  Args:
-    the options returned from OptParser.parse_options
+  @param options: the options returned from OptParser.parse_options
 
-  Returns:
-    a list of disk names, e.g. ['sda', 'sdb']
-  """
+  @return: a list of disk names, e.g. ['sda', 'sdb']
 
+  """
   sysdisks = GetDiskList(options)
   if not sysdisks:
     raise PrereqError("no disks found (I looked for"
@@ -697,8 +693,9 @@ def ValidateDiskList(options):
 
 
 def BootStrap():
-  """Actual main routine."""
+  """Actual main routine.
 
+  """
   CheckPrereq()
 
   options, args = ParseOptions()
@@ -736,11 +733,11 @@ def BootStrap():
 
 
 def main():
-  """application entry point.
+  """Application entry point.
 
   This is just a wrapper over BootStrap, to handle our own exceptions.
-  """
 
+  """
   try:
     BootStrap()
   except PrereqError, err:
