API docs: docstrings, module titles

bzr revid: xrg@linux.gr-20110623090457-y5o7pd5y1ltpo9t9

openerp/addons/base/module/report/__init__.py

@@ -21,5 +21,15 @@
 
 import ir_module_reference_print
 
+#.apidoc title: RPC Services
+
+""" Classes of this module implement the network protocols that the
+    OpenERP server uses to communicate with remote clients.
+
+    Some classes are mostly utilities, whose API need not be visible to
+    the average user/developer. Study them only if you are about to
+    implement an extension to the network protocols, or need to debug some
+    low-level behavior of the wire.
+"""
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
 

openerp/report/printscreen/__init__.py

@@ -22,6 +22,11 @@
 import ps_list
 import ps_form
 
+#.apidoc title: Printscreen Support
+
+""" A special report, that is automatically formatted to look like the
+    screen contents of Form/List Views.
+"""
 
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
 

openerp/report/printscreen/ps_list.py

@@ -31,6 +31,8 @@ import time, os
 from operator import itemgetter
 from datetime import datetime
 
+#.apidoc title: Printscreen for List Views
+
 class report_printscreen_list(report_int):
     def __init__(self, name):
         report_int.__init__(self, name)

openerp/report/pyPdf/__init__.py

@@ -1,2 +1,5 @@
 from pdf import PdfFileReader, PdfFileWriter
+#.apidoc title: pyPdf Engine
+
 __all__ = ["pdf"]
+

openerp/report/render/html2html/__init__.py

@@ -21,5 +21,7 @@
 
 from html2html import parseString
 
+#.apidoc title: HTML to HTML engine
+
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
 

openerp/report/render/makohtml2html/__init__.py

@@ -19,4 +19,7 @@
 #
 ##############################################################################
 
-from makohtml2html import parseNode
+from makohtml2html import parseNode
+
+#.apidoc title: MAKO to HTML engine
+

openerp/report/render/odt2odt/__init__.py

@@ -21,4 +21,6 @@
 
 from odt2odt import parseNode
 
+#.apidoc title: ODT to ODT engine
+
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:

openerp/report/render/rml2html/__init__.py

@@ -21,5 +21,7 @@
 
 from rml2html import parseString
 
+#.apidoc title: RML to HTML engine
+
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
 

openerp/report/render/rml2pdf/__init__.py

@@ -21,3 +21,5 @@
 
 from trml2pdf import parseString, parseNode
 
+#.apidoc title: RML to PDF engine
+

openerp/report/render/rml2pdf/customfonts.py

@@ -28,6 +28,8 @@ from reportlab import rl_config
 
 from openerp.tools import config
 
+#.apidoc title: TTF Font Table
+
 """This module allows the mapping of some system-available TTF fonts to
 the reportlab engine.
 

openerp/report/render/rml2txt/__init__.py

@@ -21,5 +21,14 @@
 
 from rml2txt import parseString, parseNode
 
+#.apidoc title: RML to TXT engine
+
+""" This engine is the minimalistic renderer of RML documents into text files,
+    using spaces and newlines to format.
+
+    It was needed in some special applications, where legal reports need to be
+    printed in special (dot-matrix) printers.
+"""
+
 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4:
 

openerp/service/http_server.py

@@ -26,10 +26,19 @@
 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 ###############################################################################
 
-""" This file contains instance of the http server.
+#.apidoc title: HTTP and XML-RPC Server
 
+""" This module offers the family of HTTP-based servers. These are not a single
+    class/functionality, but a set of network stack layers, implementing
+    extendable HTTP protocols.
 
+    The OpenERP server defines a single instance of a HTTP server, listening at
+    the standard 8069, 8071 ports (well, it is 2 servers, and ports are 
+    configurable, of course). This "single" server then uses a `MultiHTTPHandler`
+    to dispatch requests to the appropriate channel protocol, like the XML-RPC,
+    static HTTP, DAV or other.
 """
+
 from websrv_lib import *
 import openerp.netsvc as netsvc
 import errno

openerp/service/netrpc_server.py

@@ -19,6 +19,8 @@
 #
 ##############################################################################
 
+#.apidoc title: NET-RPC Server
+
 """ This file contains instance of the net-rpc server
 
     

openerp/service/security.py

@@ -22,8 +22,11 @@
 import openerp.pooler as pooler
 import openerp.tools as tools
 
-# When rejecting a password, hide the traceback
+#.apidoc title: Authentication helpers
+
 class ExceptionNoTb(Exception):
+    """ When rejecting a password, hide the traceback
+    """
     def __init__(self, msg):
         super(ExceptionNoTb, self).__init__(msg)
         self.traceback = ('','','')

openerp/service/web_services.py

@@ -38,6 +38,15 @@ import locale
 import logging
 from cStringIO import StringIO
 
+#.apidoc title: Exported Service methods
+#.apidoc module-mods: member-order: bysource
+
+""" This python module defines the RPC methods available to remote clients.
+
+    Each 'Export Service' is a group of 'methods', which in turn are RPC
+    procedures to be called. Each method has its own arguments footprint.
+"""
+
 class db(netsvc.ExportService):
     def __init__(self, name="db"):
         netsvc.ExportService.__init__(self, name)

openerp/service/websrv_lib.py

@@ -24,8 +24,12 @@
 # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 ###############################################################################
 
+#.apidoc title: HTTP Layer library (websrv_lib)
+
 """ Framework for generic http servers
 
+    This library contains *no* OpenERP-specific functionality. It should be
+    usable in other projects, too.
 """
 
 import socket

openerp/tools/config.py

@@ -45,7 +45,7 @@ class MyOption (optparse.Option, object):
         self.my_default = attrs.pop('my_default', None)
         super(MyOption, self).__init__(*opts, **attrs)
 
-#.apidoc title: Server Configuration
+#.apidoc title: Server Configuration Loader
 
 def check_ssl():
     try: