python: Document every class, function, property.

Finally, a complete reference to apt_pkg available
via pydoc and __doc__ attributes.

1 files changed, 95 insertions, 24 deletions

diff --git a/python/configuration.cc b/python/configuration.cc
index 1b5010ab..1aff56fb 100644
--- a/python/configuration.cc
+++ b/python/configuration.cc
@@ -33,7 +33,10 @@ static inline Configuration &GetSelf(PyObject *Obj)
 									/*}}}*/
 
 // Method Wrappers							/*{{{*/
-static char *doc_Find = "Find(Name[,default]) -> String/None";
+static const char *doc_Find =
+    "find(key: str[, default: str = '']) -> str\n\n"
+    "Find the value for the given key and return it. If the\n"
+    "given key does not exist, return default instead.";
 static PyObject *CnfFind(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -43,7 +46,21 @@ static PyObject *CnfFind(PyObject *Self,PyObject *Args)
    return CppPyString(GetSelf(Self).Find(Name,Default));
 }
 
-static char *doc_FindFile = "FindFile(Name[,default]) -> String/None";
+static const char *doc_FindFile =
+    "find_file(key: str[, default: str = '']) -> str\n\n"
+    "Same as find(), but for filenames. In the APT configuration, there\n"
+    "is a special section Dir:: for storing filenames. find_file() locates\n"
+    "the given key and then goes up and prepends the directory names to the\n"
+    "return value, e.g. for:\n"
+    "\n"
+    "    apt_pkg.config['Dir'] = 'a'\n"
+    "    apt_pkg.config['Dir::D'] = 'b'\n"
+    "    apt_pkg.config['Dir::D::F'] = 'c'\n"
+    "\n"
+    "find_file('Dir::D::F') returns 'a/b/c'. There is also a special\n"
+    "configuration setting RootDir which will always be prepended to the\n"
+    "result (the default being ''). Thus, if RootDir is 'x', the example\n"
+    "would return 'x/a/b/c'.";
 static PyObject *CnfFindFile(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -53,7 +70,10 @@ static PyObject *CnfFindFile(PyObject *Self,PyObject *Args)
    return CppPyString(GetSelf(Self).FindFile(Name,Default));
 }
 
-static char *doc_FindDir = "FindDir(Name[,default]) -> String/None";
+static const char *doc_FindDir =
+    "find_dir(key: str[, default: str = '']) -> str\n\n"
+    "Same as find_file(), but for directories. The difference is\n"
+    "that this function adds a trailing slash to the result.";
 static PyObject *CnfFindDir(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -63,7 +83,9 @@ static PyObject *CnfFindDir(PyObject *Self,PyObject *Args)
    return CppPyString(GetSelf(Self).FindDir(Name,Default));
 }
 
-static char *doc_FindI = "FindI(Name[,default]) -> Integer";
+static const char *doc_FindI =
+    "find_i(key: str[, default: int = 0]) -> int\n\n"
+    "Same as find, but only for integer values.";
 static PyObject *CnfFindI(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -73,7 +95,9 @@ static PyObject *CnfFindI(PyObject *Self,PyObject *Args)
    return Py_BuildValue("i",GetSelf(Self).FindI(Name,Default));
 }
 
-static char *doc_FindB = "FindB(Name[,default]) -> Integer";
+static const char *doc_FindB =
+    "find_i(key: str[, default: bool = False]) -> bool\n\n"
+    "Same as find, but only for boolean values.";
 static PyObject *CnfFindB(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -83,7 +107,11 @@ static PyObject *CnfFindB(PyObject *Self,PyObject *Args)
    return PyBool_FromLong(GetSelf(Self).FindB(Name,(Default == 0?false:true)));
 }
 
-static char *doc_Set = "Set(Name,Value) -> None";
+static const char *doc_Set =
+    "set(key: str, value: str)\n\n"
+    "Set the given key to the given value. To set int or bool values,\n"
+    "encode them using str(value). One can then use find_i()/find_b()\n"
+    "to retrieve their value again.";
 static PyObject *CnfSet(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -96,7 +124,9 @@ static PyObject *CnfSet(PyObject *Self,PyObject *Args)
    return Py_None;
 }
 
-static char *doc_Exists = "Exists(Name) -> Integer";
+static const char *doc_Exists =
+    "exists(key: str) -> bool\n\n"
+    "Check whether the given key exists.";
 static PyObject *CnfExists(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -110,7 +140,9 @@ static int CnfContains(PyObject *Self,PyObject *Arg)
    return (int)GetSelf(Self).Exists(PyString_AsString(Arg));
 }
 
-static char *doc_Clear = "Clear(Name) -> None";
+static const char *doc_Clear = 
+    "clear(key: str)\n\n"
+    "Unset the option at the given key and all sub options.";
 static PyObject *CnfClear(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -124,7 +156,12 @@ static PyObject *CnfClear(PyObject *Self,PyObject *Args)
 }
 
 // The amazing narrowing search ability!
-static char *doc_SubTree = "SubTree(Name) -> Configuration";
+static const char *doc_SubTree =
+    "sub_tree(key: str) -> apt_pkg.Configuration\n\n"
+    "Return a new apt_pkg.Configuration objects which starts at the\n"
+    "given option. Example:\n\n"
+    "    apttree = config.subtree('APT')\n"
+    "    apttree['Install-Suggests'] = config['APT::Install-Suggests']";
 static PyObject *CnfSubTree(PyObject *Self,PyObject *Args)
 {
    char *Name;
@@ -142,7 +179,9 @@ static PyObject *CnfSubTree(PyObject *Self,PyObject *Args)
 }
 
 // Return a list of items at a specific level
-static char *doc_List = "List([root]) -> List";
+static char *doc_List =
+    "list([root: str]) -> list\n\n"
+    "Return a list of all items at the given root.";
 static PyObject *CnfList(PyObject *Self,PyObject *Args)
 {
    char *RootName = 0;
@@ -169,7 +208,9 @@ static PyObject *CnfList(PyObject *Self,PyObject *Args)
 
 /* Return a list of values of items at a specific level.. This is used to
    get out value lists */
-static char *doc_ValueList = "ValueList([root]) -> List";
+static char *doc_ValueList =
+    "value_list([root: str]) -> list\n\n"
+    "Same as list(), but instead of returning the keys, return the values.";
 static PyObject *CnfValueList(PyObject *Self,PyObject *Args)
 {
    char *RootName = 0;
@@ -191,7 +232,11 @@ static PyObject *CnfValueList(PyObject *Self,PyObject *Args)
    return List;
 }
 
-static char *doc_MyTag = "MyTag() -> String";
+static char *doc_MyTag =
+    "my_tag() -> str\n\n"
+    "Return the tag of the root of this Configuration object. For the\n"
+    "default object, this is an empty string. For a subtree('APT') of\n"
+    "such an object, it would be 'APT' (given as an example).";
 static PyObject *CnfMyTag(PyObject *Self,PyObject *Args)
 {
    if (PyArg_ParseTuple(Args,"") == 0)
@@ -204,7 +249,10 @@ static PyObject *CnfMyTag(PyObject *Self,PyObject *Args)
 }
 
 // Look like a mapping
-static char *doc_Keys = "keys([root]) -> List";
+static char *doc_Keys =
+    "keys([root: str]) -> list\n\n"
+    "Return a list of all keys in the configuration object. If 'root'\n"
+    "is given, limit the list to those below the root.";
 static PyObject *CnfKeys(PyObject *Self,PyObject *Args)
 {
    char *RootName = 0;
@@ -274,7 +322,10 @@ static int CnfMapSet(PyObject *Self,PyObject *Arg,PyObject *Val)
 }
 									/*}}}*/
 // Config file loaders							/*{{{*/
-char *doc_LoadConfig = "LoadConfig(Configuration,FileName) -> None";
+char *doc_LoadConfig =
+    "read_config_file(configuration: apt_pkg.Configuration, filename: str)\n\n"
+    "Read the configuration file given by filename and set the options\n"
+    "defined therein in the configuration object.";
 PyObject *LoadConfig(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -292,7 +343,11 @@ PyObject *LoadConfig(PyObject *Self,PyObject *Args)
    Py_INCREF(Py_None);
    return HandleErrors(Py_None);
 }
-char *doc_LoadConfigISC = "LoadConfigISC(Configuration,FileName) -> None";
+char *doc_LoadConfigISC =
+    "read_config_file_isc(configuration: apt_pkg.Configuration, filename: str)\n\n"
+    "Like read_config_file(), but for configuration files like bind's\n"
+    "named.conf. They have a slightly different format than APT\n"
+    "configuration files.";
 PyObject *LoadConfigISC(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -310,7 +365,10 @@ PyObject *LoadConfigISC(PyObject *Self,PyObject *Args)
    Py_INCREF(Py_None);
    return HandleErrors(Py_None);
 }
-char *doc_LoadConfigDir = "LoadConfigDir(Configuration,DirName) -> None";
+char *doc_LoadConfigDir =
+    "read_config_dir(configuration: apt_pkg.Configuration, dirname: str)\n\n"
+    "Read all configuration files in the dir given by 'dirname' in the\n"
+    "correct order.";
 PyObject *LoadConfigDir(PyObject *Self,PyObject *Args)
 {
    char *Name = 0;
@@ -333,14 +391,19 @@ PyObject *LoadConfigDir(PyObject *Self,PyObject *Args)
 // ParseCommandLine - Wrapper for the command line interface		/*{{{*/
 // ---------------------------------------------------------------------
 char *doc_ParseCommandLine =
-"ParseCommandLine(Configuration,ListOfOptions,List-argv) -> List\n"
+"parse_commandLine(config: Configuration, options: list, argv: list) -> list\n"
 "\n"
-"This function is like getopt except it manipulates a configuration space.\n"
-"output is a list of non-option arguments (filenames, etc).\n"
-"ListOfOptions is a list of tuples of the form:\n"
-"  ('c',\"long-opt or None\",\"Configuration::Variable\",\"optional type\")\n"
-"Where type may be one of HasArg, IntLevel, Boolean, InvBoolean,\n"
-"ConfigFile, or ArbItem. The default is Boolean.";
+"Parse the command line in 'argv' into the configuration space. The\n"
+"list 'options' contains a list of 3-tuples or 4-tuples in the form:\n"
+"\n"
+"   (short_option: str, long_option: str, variable: str[, type: str])\n"
+"\n"
+"The element 'short_option' is one character, the 'long_option' element\n"
+"is the name of the long option, the element 'variable' the name of the\n"
+"configuration option the result will be stored in and type is one of\n"
+"'HasArg', 'IntLevel', 'Boolean', 'InvBoolean', 'ConfigFile',\n"
+"'ArbItem'. The default type is 'Boolean'. Read the online documentation\n"
+"and the tutorial therin about writing an apt-cdrom clone for more details.";
 PyObject *ParseCommandLine(PyObject *Self,PyObject *Args)
 {
    PyObject *POList;
@@ -465,6 +528,14 @@ static PyObject *CnfNew(PyTypeObject *type, PyObject *args, PyObject *kwds) {
 // Type for a Normal Configuration object
 static PySequenceMethods ConfigurationSeq = {0,0,0,0,0,0,0,CnfContains,0,0};
 static PyMappingMethods ConfigurationMap = {0,CnfMap,CnfMapSet};
+
+static const char *configuration_doc =
+    "Configuration()\n\n"
+    "Configuration objects represent the configuration of apt. They map\n"
+    "keys to values and store configuration parsed from files like\n"
+    "/etc/apt/apt.conf. The most important object is apt_pkg.config\n"
+    "which points to the global configuration object. Additional objects\n"
+    "can be created, but this is normally not needed.";
 PyTypeObject PyConfiguration_Type =
 {
    PyVarObject_HEAD_INIT(&PyType_Type, 0)
@@ -489,7 +560,7 @@ PyTypeObject PyConfiguration_Type =
    0,                                   // tp_as_buffer
    (Py_TPFLAGS_DEFAULT |                // tp_flags
     Py_TPFLAGS_BASETYPE),
-   "Configuration Object",              // tp_doc
+   configuration_doc,                   // tp_doc
    0,                                   // tp_traverse
    0,                                   // tp_clear
    0,                                   // tp_richcompare