[IMP] add documentation

also replace the %(path:)s by %(menu:)s (more cohesive)

bzr revid: abo@openerp.com-20130122162223-no1wzf1gyxpdvzqk

openerp/addons/base/res/res_config.py

@@ -591,6 +591,15 @@ class res_config_settings(osv.osv_memory):
         return [(record.id, name) for record in self.browse(cr, uid , ids, context=context)]
 
     def get_option_path(self, cr, uid, menu_xml_id=None, context=None):
+        """
+        Fetch the path to a specified configuration view.
+
+        :param string menu_xml_id: the xml id of the menuitem where the view
+        is located, structured as follows: module_name.menuitem_xml_id
+        (e.g.: "base.menu_sale_config")
+        :return string: full path to the menuitem
+        (e.g.: "Settings/Configuration/Sales")
+        """
         module_name, menu_xml_id = menu_xml_id.split('.')
         dummy, menu_id = self.pool.get('ir.model.data').get_object_reference(cr, uid, module_name, menu_xml_id)
         ir_ui_menu = self.pool.get('ir.ui.menu').browse(cr, uid, menu_id, context=context)
@@ -598,13 +607,41 @@ class res_config_settings(osv.osv_memory):
         return ir_ui_menu.complete_name
 
     def get_option_name(self, cr, uid, full_field_name=None, context=None):
+        """
+        Fetch the human readable name of a specified configuration option.
+
+        :param string full_field_name: the full name of the field, structured
+        as follows: model_name.field_name
+        (e.g.: "sale.config.settings.fetchmail_lead")
+        :return string: human readable name of the field
+        (e.g.: "Create leads from incoming mails")
+        """
         model_name, field_name = full_field_name.rsplit('.', 1)
 
         return self.pool.get(model_name)._all_columns.get(field_name).column.string
 
 def get_warning_config(cr, msg, context=None):
+    """
+    Helper: return a WarningConfig exception with the given message where the
+    %(field:)s and/or %(menu:)s are replaced by the human readable field's name
+    and/or menuitem's full path.
+
+    Usage:
+    ------
+    Just include in your error message %(field:model_name.field_name)s to
+    obtain the human readable field's name, and/or
+    %(menu:module_name.menuitem_xml_id)s to obtain the menuitem's full path.
+
+    Example of use:
+    ---------------
+    from openerp.addons.base.res.res_config import get_warning_config
+    raise get_warning_config(cr, _("Error: this action is prohibited. You should check the field %(field:sale.config.settings.fetchmail_lead)s in %(menu:base.menu_sale_config)s."), context=context)
+    will return an exception containing the following message:
+    Error: this action is prohibited. You should check the field Create leads from incoming mails in Settings/Configuration/Sales.
+    """
+
     res_config_obj = pooler.get_pool(cr.dbname).get('res.config.settings')
-    regex_path = r'%\(((?:path|field):[a-z_\.]*)\)s'
+    regex_path = r'%\(((?:menu|field):[a-z_\.]*)\)s'
 
     # Process the message
     # 1/ find the path and/or field references, put them in a list
@@ -615,7 +652,7 @@ def get_warning_config(cr, msg, context=None):
     values = {}
     for item in references:
         ref_type, ref = item.split(':')
-        if ref_type == 'path':
+        if ref_type == 'menu':
             values[item] = res_config_obj.get_option_path(cr, SUPERUSER_ID, ref, context)
         elif ref_type == 'field':
             values[item] = res_config_obj.get_option_name(cr, SUPERUSER_ID, ref, context)