[glom] Python module: Improve API documentation.

[Murray Cumming <murrayc src gnome org>]

commit 78f73328741e4db9f0c69886296a244ccd808770
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu Apr 15 10:43:19 2010 +0200

    Python module: Improve API documentation.
    
    * glom/python_embed/python_module/py_glom_module.cc: Added some options and
    text for docstrings, to improve the pydoc -w output.

 ChangeLog                                         |    7 +++
 glom/python_embed/python_module/py_glom_module.cc |   54 +++++++++++++++-----
 2 files changed, 47 insertions(+), 14 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 8ded4cb..f54846f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2010-04-15  Murray Cumming  <murrayc murrayc com>
+
+  Python module: Improve API documentation.
+  
+	* glom/python_embed/python_module/py_glom_module.cc: Added some options and 
+	text for docstrings, to improve the pydoc -w output.
+
 1.14.0:
 
 2010-04-14  Murray Cumming  <murrayc murrayc com>
diff --git a/glom/python_embed/python_module/py_glom_module.cc b/glom/python_embed/python_module/py_glom_module.cc
index e036427..6e52d91 100644
--- a/glom/python_embed/python_module/py_glom_module.cc
+++ b/glom/python_embed/python_module/py_glom_module.cc
@@ -21,6 +21,7 @@
 #include <config.h>
 //We need to include this before anything else, to avoid redefinitions:
 #include <boost/python.hpp>
+
 //#include <compile.h> /* for the PyCodeObject */
 //#include <eval.h> /* for PyEval_EvalCode */
 
@@ -33,10 +34,22 @@ using namespace Glom;
 
 BOOST_PYTHON_MODULE(glom_1_14)
 {
-  boost::python::class_<PyGlomRecord>("Record")
-    .add_property("table_name", &PyGlomRecord::get_table_name)
-    .add_property("connection", &PyGlomRecord::get_connection)
-    .add_property("related", &PyGlomRecord::get_related)
+  boost::python::docstring_options doc_options(
+    true, // show the docstrings from here
+    true, // show Python signatures.
+    false); // Don't mention the C++ method signatures in the generated docstrings.
+  boost::python::class_<PyGlomRecord>("Record", 
+    "The current record of the current table.\n"
+    "Use record['field_name'] to get the value of a specified field in the current record.\n"
+    "Use record.related['relationship_name']['field_name'] to get the value of a specified field in a related record.\n"
+    "Use record.related['relationship_name'].sum('field_name') to get a sum of all the values of a specified field in multiple related records. See the RelatedRecord object for more aggregate functions."
+    )
+    .add_property("table_name", &PyGlomRecord::get_table_name,
+       "The name of the current table.")
+    .add_property("connection", &PyGlomRecord::get_connection,
+       "The current database connection for use with the pygda API.")
+    .add_property("related", &PyGlomRecord::get_related,
+       "Related records. Use the ['relationship_name'] notation with this object.")
 
     .def("__getitem__", &PyGlomRecord::getitem)
     .def("__setitem__", &PyGlomRecord::setitem)
@@ -49,19 +62,32 @@ BOOST_PYTHON_MODULE(glom_1_14)
   ;
 
   boost::python::class_<PyGlomRelatedRecord>("RelatedRecord")
-    .def("sum", &PyGlomRelatedRecord::sum, boost::python::args("field_name"), "Add all values of the field in the related records.")
-    .def("count", &PyGlomRelatedRecord::sum, boost::python::args("field_name"), "Count all values in the field in the related records.")
-    .def("min", &PyGlomRelatedRecord::sum, boost::python::args("field_name"), "Minimum of all values of the field in the related recordss.")
-    .def("max", &PyGlomRelatedRecord::sum, boost::python::args("field_name"), "Maximum of all values of the field in the related records.")
+    .def("sum", &PyGlomRelatedRecord::sum, boost::python::args("field_name"),
+      "Add all values of the field in the related records.")
+    .def("count", &PyGlomRelatedRecord::sum, boost::python::args("field_name"),
+      "Count all values in the field in the related records.")
+    .def("min", &PyGlomRelatedRecord::sum, boost::python::args("field_name"),
+      "Minimum of all values of the field in the related recordss.")
+    .def("max", &PyGlomRelatedRecord::sum, boost::python::args("field_name"),
+      "Maximum of all values of the field in the related records.")
     .def("__getitem__", &PyGlomRelatedRecord::getitem)
     .def("__len__", &PyGlomRelatedRecord::len)
   ;
 
-  boost::python::class_<PyGlomUI>("UI")
-    .def("show_table_details", &PyGlomUI::show_table_details)
-    .def("show_table_list", &PyGlomUI::show_table_list)
-    .def("print_layout", &PyGlomUI::print_layout)
-    .def("print_report", &PyGlomUI::print_report)
-    .def("start_new_record", &PyGlomUI::start_new_record)
+  boost::python::class_<PyGlomUI>("UI",
+    "A collection of methods to programatically change the Glom UI, performing tasks that might otherwise be done by the user via the mouse and keyboard.")
+    .def("show_table_details", &PyGlomUI::show_table_details,
+      boost::python::args("table_name", "primary_key_value"),
+      "Navigate to the specified table, showing its details view for the specified record.")
+    .def("show_table_list", &PyGlomUI::show_table_list,
+       boost::python::args("table_name"),
+      "Navigate to the specified table, showing its list view.")
+    .def("print_layout", &PyGlomUI::print_layout,
+      "Print the current layout for the current table.")
+    .def("print_report", &PyGlomUI::print_report,
+      boost::python::args("report_name"),
+      "Print the specified report for the current table.")
+    .def("start_new_record", &PyGlomUI::start_new_record,
+      "Start a new empty record for the current table, offering the empty record in the UI.")
   ;
 }