Some docstring fixes

lodel/editorial_model/translator/xmlfile.py

@@ -16,17 +16,19 @@ LodelContext.expose_modules(globals(), {
 #
 # Structure of a xml file which represents an editorial model:
 # <ul>
-# <li>\<name\>: name of the model, field <b><em>name</em></b>  in class <b><em>EditorialModel</em></b> 
-# <li>\<description\>: field <b><em>description</em></b>  of a composed element, one for each language translation named 
-#               <ul><li>\<fre\> for french, 
-#               <li>\<eng\> for english,
-#               <li>\<esp\> for spanish,
-#               <li>\<ger\> for german</ul>
-# <li>\<classes\>: set of all <b><em>EmClass</em></b> in the model \n
+#   <li>\<name\>: name of the model, field <b><em>name</em></b>  in class <b><em>EditorialModel</em></b>
+#   <li>\<description\>: field <b><em>description</em></b>  of a composed element, one for each language translation named
+#               <ul>
+#                   <li>\<fre\> for french,
+#                   <li>\<eng\> for english,
+#                   <li>\<esp\> for spanish,
+#                   <li>\<ger\> for german
+#               </ul>
+#   <li>\<classes\>: set of all <b><em>EmClass</em></b> in the model \n
 #    for each classe: \n
 #       \<class\><ul>
-#       <li>\<uid\>the class's id
-#       <li>\<display_name\> The name of the class, field <b><em>display_name</em></b>  of the <b><em>EmClass</em></b> , in different languages if they're available :
+#           <li>\<uid\>the class's id
+#           <li>\<display_name\> The name of the class, field <b><em>display_name</em></b>  of the <b><em>EmClass</em></b> , in different languages if they're available :
 #               <ul><li>\<fre\> for french, 
 #               <li>\<eng\> for english,
 #               <li>\<esp\> for spanish,
@@ -43,8 +45,9 @@ LodelContext.expose_modules(globals(), {
 #               <li>\<help_text\> Short explanation of the class's purpose, in different languages, as above
 #               <li>\<group\><b><em>uid</em></b> of the group of the field <b><em>group</em></b> of the <b><em>EmClass</em></b>
 #               <li>\<datahandler_name\> field <b><em>datahandler_name</em></b> of the Emfield, the name of a datahandler
-#               <li>\<datahandler_options\>, a list of xml items, each of them named with an option name and contains its value</ul></ul>
-# <li>\<groups\>: set of all the groups <b><em>EmGroup</em></b> in the model\n
+#               <li>\<datahandler_options\>, a list of xml items, each of them named with an option name and contains its value</ul>
+#               </ul>
+#   <li>\<groups\>: set of all the groups <b><em>EmGroup</em></b> in the model\n
 #    for each group:\n
 #       <ul><li>\<uid\> uid of the <b><em>EmField</em></b>
 #       <li>\<display_name\> field <b><em>display_name</em></b>  of the <b><em>EmField</em></b>, in different languages, as above
@@ -58,7 +61,7 @@ LodelContext.expose_modules(globals(), {
 #           <li>\<emclasses\> all the emclasses with, for each of them:\n
 #               \<emclass\> \n
 #                   <ul><li> \<uid\> <b><em>uid</em></b> of the <b><em>EmClass</em></b></ul></ul></ul>
-
+# </ul>
 
 
 
@@ -66,8 +69,8 @@ LodelContext.expose_modules(globals(), {
 
 ##@brief Saves a model in a xml file
 # @param model EditorialModel : the model to save
-# @param filename str|None : if None display on stdout else writes in the file filename
-
+# @param kwargs dict :
+#    - filename str|None : if None display on stdout else writes in the file filename
 def save(model, **kwargs):
     Em = etree.Element("editorial_model")
     em_name = etree.SubElement(Em, 'name')
@@ -144,9 +147,9 @@ def write_datahandler_xml(etree, elem, dhdl_name, **kwargs):
 # @param uid : the uid of the EmField
 # @param name : the name of the field
 # @param help_text : explanations of the EmField
-# @param group_uid : the uid of a group, can be None
-# @datahandler_name
-# @**kwargs : options of the datahandler
+# @param group : the uid of a group, can be None
+# @param datahandler_name str
+# @param **kwargs : options of the datahandler
 def write_emfield_xml(etree, elem, uid, name, help_text, group, datahandler_name, **kwargs):
     emfield = etree.SubElement(elem,'field')
     emfield_uid = etree.SubElement(emfield, 'uid')
@@ -170,9 +173,11 @@ def write_emfield_xml(etree, elem, uid, name, help_text, group, datahandler_name
 ##@brief Writes a representation of a EmGroup in xml
 # @param etree : the xml object
 # @param elem : the element for the EmGroup
+# @param uid str : lodel unique identifier
 # @param name  : the name of the group
 # @param help_text : explanations of the EmGroup
 # @param requires : a list of the group's uids whose this group depends
+# @param components
 def write_emgroup_xml(etree, elem, uid, name, help_text, requires, components):
     emgroup = etree.SubElement(elem, 'group')
     emgroup_uid = etree.SubElement(emgroup, 'uid')
@@ -207,8 +212,10 @@ def write_emgroup_xml(etree, elem, uid, name, help_text, requires, components):
 ##@brief Writes a representation of a EmClass in xml
 # @param etree : the xml object
 # @param elem : the element for the EmClass
+# @param uid
 # @param name  : the name of the group
 # @param help_text : explanations of the EmClass
+# @param group
 # @param fields : a dict
 # @param parents : a list of EmClass uids
 # @param abstract : a boolean
@@ -245,7 +252,7 @@ def write_emclass_xml(etree, elem, uid, name, help_text, group, fields, parents,
     emclass_parents.text = ",".join(parents_list)
 
 ##@brief Loads a model from a xml file
-# @param model EditorialModel : the model to load
+# @param filename str : file path of the XML file from which the model will be loaded
 # @return a new EditorialModel object
 def load(filename):
 
@@ -452,7 +459,6 @@ def load_group_xml(model, elem):
 
 ##@brief Constructs a MlString from a xml description
 # @param elem : the element which represents the MlString
-# @param model  : the model which will contain the new group
 # @return a new MlString object
 def load_mlstring_xml(elem):
     mlstr = dict()

lodel/leapi/datahandlers/base_classes.py

@@ -36,10 +36,13 @@ class DataHandler(object):
 
     directly_editable = True
     ##@brief constructor
-    # @param internal False | str : define whether or not a field is internal
-    # @param immutable bool : indicates if the fieldtype has to be defined in child classes of LeObject or if it is
-    #                         designed globally and immutable
-    # @param **args
+    # @param **kwargs dict
+    #   - internal False | str : define whether or not a field is internal
+    #   - immutable bool : indicates if the fieldtype has to be defined in child classes of LeObject or if it is designed globally and immutable
+    #   - nullable bool
+    #   - uniq bool
+    #   - primary_key bool
+    #   - default mixed
     # @throw NotImplementedError if it is instanciated directly
     def __init__(self, **kwargs):
         if self.__class__ == DataHandler:
@@ -143,7 +146,7 @@ class DataHandler(object):
     #@param cur_value : the value from the current field (identified by fieldname)
     #@return the value
     #@see construct_data() lodel2_dh_check_impl
-    def _construct_data(self, empcomponent, fname, datas, cur_value):
+    def _construct_data(self, emcomponent, fname, datas, cur_value):
         return cur_value
 
     ##@brief Check datas consistency
@@ -206,21 +209,21 @@ class DataHandler(object):
     # @return DataField child class
     # @note To access custom data handlers it can be cool to prefix the handler name by plugin name for example ? (to ensure name unicity)
     @classmethod
-    def from_name(cls, name):
+    def from_name(cls, fieldtype_name):
         cls.load_base_handlers()
         all_handlers = dict(cls._base_handlers, **cls.__custom_handlers)
-        name = name.lower()
-        if name not in all_handlers:
-            raise NameError("No data handlers named '%s'" % (name,))
-        return all_handlers[name]
+        fieldtype_name = fieldtype_name.lower()
+        if fieldtype_name not in all_handlers:
+            raise NameError("No data handlers named '%s'" % (fieldtype_name,))
+        return all_handlers[fieldtype_name]
 
     ##@brief Return the module name to import in order to use the datahandler
     # @param data_handler_name str : Data handler name
     # @return a str
     @classmethod
-    def module_name(cls, name):
-        name = name.lower()
-        handler_class = cls.from_name(name)
+    def module_name(cls, data_handler_name):
+        data_handler_name = data_handler_name.lower()
+        handler_class = cls.from_name(data_handler_name)
         return '{module_name}.{class_name}'.format(
                                                     module_name=handler_class.__module__,
                                                     class_name=handler_class.__name__
@@ -386,6 +389,7 @@ class MultipleRef(Reference):
 
     ##
     # @param max_item int | None : indicate the maximum number of item referenced by this field, None mean no limit
+    # @param kwargs dict
     def __init__(self, max_item=None, **kwargs):
         self.max_item = max_item
         super().__init__(**kwargs)
@@ -421,7 +425,7 @@ class MultipleRef(Reference):
         return new_val
 
     ##@brief Utility method designed to fetch referenced objects
-    #@param value mixed : the field value
+    #@param values mixed : the field value
     #@return A list of LeObject child class instance
     #@throw LodelDataHandlerConsistencyException if some referenced objects
     #were not found
@@ -453,7 +457,7 @@ some referenced objects. Followinf uid were not found : %s" % ','.join(left))
 class DatasConstructor(object):
 
     ## @brief Init a DatasConstructor
-    # @param lec LeCrud : @ref LeObject child class
+    # @param leobject LeCrud : @ref LeObject child class
     # @param datas dict : dict with field name as key and field values as value
     # @param fields_handler dict : dict with field name as key and data handler instance as value
     def __init__(self, leobject, datas, fields_handler):

lodel/leapi/datahandlers/datas.py

@@ -21,7 +21,6 @@ build its content'
     
     ##@brief Build its content with a field list and a format string
     # @param format_string str
-    # @param max_length int : the maximum length of the handled value
     # @param field_list list : List of field to use
     # @param **kwargs
     def __init__(self, format_string, field_list, **kwargs):
@@ -115,7 +114,6 @@ class Concat(FormatString):
     
     ##@brief Build its content with a field list and a separator
     # @param field_list list : List of field to use
-    # @param max_length int : the maximum length of the handled value
     # @param separator str
     # @param **kwargs    
     def __init__(self, field_list, separator = ' ', **kwargs):

lodel/leapi/datahandlers/datas_base.py

@@ -45,7 +45,8 @@ class Integer(DataField):
 
     ##@brief Check and cast value in appropriate type
     #@param value *
-    #@throw FieldValidationError if value is unappropriate or can not be cast 
+    #@param strict bool : if True, checks if the given value is strictly of the Integer type, if False, it tries to cast it to an Integer
+    #@throw FieldValidationError if value is unappropriate or can not be cast
     #@return value
     def _check_data_value(self, value, strict = False):
         value = super()._check_data_value(value)

lodel/leapi/datahandlers/references.py

@@ -16,8 +16,7 @@ class Link(SingleRef):
 class List(MultipleRef):
 
     ##@brief instanciates a list reference
-    # @param allowed_classes list | None : list of allowed em classes if None no restriction
-    # @param internal bool
+    # @param max_length
     # @param kwargs
     def __init__(self, max_length = None, **kwargs):
         super().__init__(**kwargs)
@@ -43,8 +42,6 @@ a list : %s" % e)
 class Set(MultipleRef):
 
     ##@brief instanciates a set reference
-    # @param allowed_classes list | None : list of allowed em classes if None no restriction
-    # @param internal bool : if False, the field is not internal
     # @param kwargs : Other named arguments
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
@@ -69,8 +66,6 @@ a set : %s" % e)
 class Map(MultipleRef):
 
     ##@brief instanciates a dict reference
-    # @param allowed_classes list | None : list of allowed em classes if None no restriction
-    # @param internal bool : if False, the field is not internal
     # @param kwargs : Other named arguments
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
@@ -97,6 +92,7 @@ class Hierarch(MultipleRef):
     # @param back_reference tuple : Here it is mandatory to have a back ref (like a parent field)
     # @param max_depth int | None :  limit of depth
     # @param max_childs int | Nine : maximum number of childs by nodes
+    # @param kwargs
     def __init__(self, back_reference, max_depth = None, max_childs = None, **kwargs):
         super().__init__(   back_reference = back_reference,
                             max_depth = max_depth,

lodel/leapi/lefactory.py

@@ -115,7 +115,6 @@ def forge_optval(optval):
 
 ##@brief Generate dyncode from an EmClass
 # @param model EditorialModel : 
-# @param emclass EmClass : EmClass instance
 # @todo delete imports. It is never use, consequently changed return parameters.
 # @return a tuple with emclass python code, a set containing modules name to import, and a list of python instruction to bootstrap dynamic code, in this order
 def generate_classes(model):

lodel/leapi/lefactory_common.py

@@ -17,7 +17,7 @@ def name2class(name):
 ##@brief Return a dynamically generated class given it's name
 #@note Case insensitive version of name2class
 #@param name str
-#@retrun False or a child class of LeObject
+#@return False or a child class of LeObject
 def lowername2class(name):
     name = name.lower()
     new_dict = {k.lower():v for k,v in dynclasses_dict.items()}

lodel/leapi/leobject.py

@@ -294,7 +294,7 @@ class LeObject(object):
 
     ##@brief Read only access to all datas
     # @note for fancy data accessor use @ref LeObject.g attribute @ref LeObjectValues instance
-    # @param name str : field name
+    # @param field_name str : field name
     # @return the Value
     # @throw RuntimeError if the field is not initialized yet
     # @throw NameError if name is not an existing field name
@@ -516,6 +516,7 @@ construction and consitency when datas are not complete\n")
     # @warning assert that datas is complete
     # @param cls
     # @param datas dict : Datas that have been returned by LeCrud.prepare_datas() method
+    # @param type_query str : Type of query
     @classmethod
     def make_consistency(cls, datas, type_query = 'insert'):
         for fname, dh in cls._fields.items():
@@ -565,8 +566,8 @@ construction and consitency when datas are not complete\n")
         return result
     
     ## @brief Delete instances of LeObject
-    #@param uids a list: lists of (fieldname, fieldvalue), with fieldname in cls._uids
-    #@returns the 
+    #@param query_filters list: lists of (fieldname, fieldvalue), with fieldname in cls._uids
+    #@returns the number of deleted items
     @classmethod
     def delete_bundle(cls, query_filters):
         deleted = 0
@@ -585,7 +586,6 @@ construction and consitency when datas are not complete\n")
             
     ## @brief Get instances of LeObject
     #
-    #@param target_class LeObject : class of object the query is about
     #@param query_filters dict : (filters, relational filters), with filters is a list of tuples : (FIELD, OPERATOR, VALUE) )
     #@param field_list list|None : list of string representing fields see 
     #@ref leobject_filters
@@ -593,7 +593,6 @@ construction and consitency when datas are not complete\n")
     #@param group list : A list of field names or tuple (FIELDNAME,[ASC | DESC])
     #@param limit int : The maximum number of returned results
     #@param offset int : offset
-    #@param Inst
     #@return a list of items (lists of (fieldname, fieldvalue))
     @classmethod
     def get(cls, query_filters, field_list=None, order=None, group=None, limit=None, offset=0):