update the docs for the ui common module

deluge/ui/common.py

@@ -2,7 +2,7 @@
 #
 # deluge/ui/common.py
 #
-# Copyright (C) Damien Churchill 2008 <damoxc@gmail.com>
+# Copyright (C) Damien Churchill 2008-2009 <damoxc@gmail.com>
 # Copyright (C) Andrew Resch 2009 <andrewresch@gmail.com>
 #
 # This program is free software; you can redistribute it and/or modify
@@ -54,8 +54,10 @@ def decode_string(s, encoding="utf8"):
     `:param:encoding` then it will try to detect the string encoding and
     decode it.
 
-    :param s: str to decode
+    :param s: string to decode
-    :param encoding: str, the encoding to use in the decoding
+    :type s: string
+    :keyword encoding: the encoding to use in the decoding
+    :type encoding: string
 
     """
 
@@ -66,6 +68,13 @@ def decode_string(s, encoding="utf8"):
     return s
 
 class TorrentInfo(object):
+    """
+    Collects information about a torrent file.
+    
+    :param filename: The path to the torrent
+    :type filename: string
+    
+    """
     def __init__(self, filename):
         # Get the torrent data from the torrent file
         try:
@@ -140,37 +149,72 @@ class TorrentInfo(object):
         Return the torrent info as a dictionary, only including the passed in
         keys.
 
-        :param *keys: str, a number of key strings
+        :param keys: a number of key strings
+        :type keys: string
         """
         return dict([(key, getattr(self, key)) for key in keys])
 
     @property
     def name(self):
+        """
+        The name of the torrent.
+        
+        :rtype: string
+        """
         return self.__m_name
 
     @property
     def info_hash(self):
+        """
+        The torrents info_hash
+        
+        :rtype: string
+        """
         return self.__m_info_hash
 
     @property
     def files(self):
+        """
+        A list of the files that the torrent contains.
+        
+        :rtype: list
+        """
         return self.__m_files
 
     @property
     def files_tree(self):
+        """
+        A dictionary based tree of the files.
+        
+        ::
+        
+            {
+                "some_directory": {
+                    "some_file": (index, size, download)
+                }
+            }
+        
+        :rtype: dictionary
+        """
         return self.__m_files_tree
 
     @property
     def metadata(self):
+        """
+        The torrents metadata.
+        
+        :rtype: dictionary
+        """
         return self.__m_metadata
 
 class FileTree(object):
-    def __init__(self, paths):
+    """
-        """
+    Convert a list of paths in a file tree.
-        Convert a list of paths in a file tree.
 
-        :param paths: list, The paths to be converted.
+    :param paths: list, The paths to be converted.
-        """
+    """
+    
+    def __init__(self, paths):
         self.tree = {}
 
         def get_parent(path):
@@ -196,7 +240,8 @@ class FileTree(object):
         """
         Return the tree, after first converting all file lists to a tuple.
 
-        :returns: dict, the file tree.
+        :returns: the file tree.
+        :rtype: dictionary
         """
         def to_tuple(path, item):
             if type(item) is dict:
@@ -210,9 +255,10 @@ class FileTree(object):
         Walk through the file tree calling the callback function on each item
         contained.
 
-        :param callback: function, The function to be used as a callback, it
+        :param callback: The function to be used as a callback, it should have
-            should have the signature func(item, path) where item is a `tuple`
+            the signature func(item, path) where item is a `tuple` for a file
-            for a file and `dict` for a directory.
+            and `dict` for a directory.
+        :type callback: function
         """
         def walk(directory, parent_path):
             for path in directory.keys():

docs/source/modules/ui/common.rst

@@ -1,5 +1,5 @@
 :mod:`deluge.ui.common`
-====================
+=======================
 
 .. automodule:: deluge.ui.common
   :members: