Some Doxygen comments fix

EditorialModel/backend/json_backend.py

@@ -87,7 +87,9 @@ class EmBackendJson(EmBackendDummy):
         return data
 
     ## Saves the data in the data source json file
-    # @param filename str : The filename to save the EM in (if None use self.json_file provided at init )
+    # @param model Model : The editorial model
+    # @param filename str|None : The filename to save the EM in (if None use self.json_file provided at init )
+    # @return json string
     def save(self, model, filename=None):
         json_dump = json.dumps({component.uid: component.attr_flat() for component in model.components()}, default=self.date_handler, indent=True)
         if self._json_file:

EditorialModel/backend/lodel1_backend.py

@@ -102,7 +102,7 @@ class EmBackendLodel1(EmBackendDummy):
         return new_dic
 
     ## convert collection of dom element to a dict
-    # <col name="id">252</col> => {'id':'252'}
+    # \<col name="id"\>252\</col\> => {'id':'252'}
     def _dom_elements_to_dict(self, elements):
         fields = {}
         for element in elements:

EditorialModel/classtypes.py

@@ -125,6 +125,7 @@ class EmClassType(object):
     }
 
     ## @brief return a classtype from its name
+    # @param cls 
     # @param classtype str : A classtype name
     # @return None if no classtype with this name, else return a dict containing classtype informations
     @classmethod
@@ -140,11 +141,9 @@ class EmClassType(object):
     def getall(cls):
         return [cls.entity, cls.entry, cls.person]
 
-    ## natures (Method)
+    ## @brief Return possible nature of relations for a classtype name
     #
-    # Return possible nature of relations for a classtype name
-    #
-    # @param classtype str: The classtype name
+    # @param classtype_name str: The classtype name
     # @return A list of EmNature names (list of str)
     @staticmethod
     def natures(classtype_name):

EditorialModel/components.py

@@ -11,11 +11,10 @@ import EditorialModel
 from Lodel.utils.mlstring import MlString
 
 
-## This class is the mother class of all editorial model objects
+## @brief This class is the mother class of all editorial model objects
 #
 # It gather all the properties and mechanism that are common to every editorial model objects
 # @see EditorialModel::classes::EmClass, EditorialModel::types::EmType, EditorialModel::fieldgroups::EmFieldGroup, EditorialModel::fields::EmField
-# @pure
 class EmComponent(object):
 
     ## Used by EmComponent::modify_rank

EditorialModel/fields.py

@@ -28,7 +28,6 @@ class EmField(EmComponent):
     # @param internal str|bool : If False the field is not internal, else it can takes value in "object" or "automatic"
     # @param rel_field_id int|None : If not None indicates that the field is a relation attribute (and the value is the UID of the rel2type field)
     # @param nullable bool : If True None values are allowed
-    # @param default * : Default field value
     # @param uniq bool : if True the value should be uniq in the db table
     # @param **kwargs : more keywords arguments for the fieldtype
     def __init__(self, model, uid, name, fieldgroup_id, fieldtype, optional=False, internal=False, rel_field_id=None, icon='0', string=None, help_text=None, date_update=None, date_create=None, rank=None, nullable=False, uniq=False, **kwargs):

EditorialModel/fieldtypes/datetime.py

@@ -11,6 +11,7 @@ class EmFieldType(GenericFieldType):
     ## @brief A datetime field
     # @param now_on_update bool : If true the date is set to NOW on update
     # @param now_on_create bool : If true the date is set to NEW on creation
+    # @param **kwargs
     def __init__(self, now_on_update=False, now_on_create=False, **kwargs):
         self.now_on_update = now_on_update
         self.now_on_create = now_on_create

EditorialModel/fieldtypes/generic.py

@@ -16,7 +16,6 @@ class GenericFieldType(object):
     
     ## @brief Instanciate a new fieldtype
     # @param ftype str : The type of datas handled by this fieldtype
-    # @param default ? : The default value
     # @param nullable bool : is None allowed as value ?
     # @param check_function function : A callback check function that takes 1 argument and raise a TypeError if the validation fails
     # @param uniq bool : Indicate if a field should handle uniq values

EditorialModel/fieldtypes/regexchar.py

@@ -10,12 +10,13 @@ class EmFieldType(EditorialModel.fieldtypes.char.EmFieldType):
     ## @brief A char field validated with a regex
     # @param regex str : a regex string (passed as argument to re.compile() )
     # @param max_length int : the maximum length for this field
-    def __init__(self, regex='', **kwargs):
+    # @param **kwargs
+    def __init__(self, regex='', max_length = 10, **kwargs):
         self.regex = regex
         v_re = re.compile(regex)  # trigger an error if invalid regex
         
         def re_match(value):
             if not v_re.match(regex, value):
                 raise TypeError('"%s" don\'t match the regex "%s"'%(value, regex))
-        super(EmFieldType, self).__init__(check_function=re_match,**kwargs)
+        super(EmFieldType, self).__init__(check_function=re_match, max_length=max_length, **kwargs)
 

EditorialModel/model.py

@@ -1,7 +1,7 @@
 #-*- coding: utf-8 -*-
 
-## @file editorialmodel.py
-# Manage instance of an editorial model
+## @package EditorialModel.model
+# Contains the class managing and editorial model
 
 import EditorialModel
 from EditorialModel.migrationhandler.dummy import DummyMigrationHandler
@@ -14,7 +14,7 @@ from EditorialModel.exceptions import EmComponentCheckError, EmComponentNotExist
 import hashlib
 
 
-## Manages the Editorial Model
+## @brief Manages the Editorial Model
 class Model(object):
 
     components_class = [EmClass, EmType, EmFieldGroup, EmField]
@@ -22,6 +22,7 @@ class Model(object):
     ## Constructor
     #
     # @param backend unknown: A backend object instanciated from one of the classes in the backend module
+    # @param migration_handler : A migration handler
     def __init__(self, backend, migration_handler=None):
         if migration_handler is None:
             self.migration_handler = DummyMigrationHandler()
@@ -145,7 +146,7 @@ class Model(object):
         return False
 
     ## Sort components by rank in Model::_components
-    # @param emclass pythonClass : The type of components to sort
+    # @param component_class pythonClass : The type of components to sort
     # @throw AttributeError if emclass is not valid
     # @warning disabled the test on component_class because of EmField new way of working
     def sort_components(self, component_class):
@@ -164,6 +165,9 @@ class Model(object):
     #
     # @note if datas does not contains a rank the new component will be added last
     # @note datas['rank'] can be an integer or two specials strings 'last' or 'first'
+    #
+    # @warning The uid parameter is designed to be used only by Model.load()
+    # @param uid int|None : If given, don't generate a new uid
     # @param component_type str : a component type ( component_class, component_fieldgroup, component_field or component_type )
     # @param datas dict : the options needed by the component creation
     # @return The created EmComponent

EditorialModel/randomem.py

@@ -47,6 +47,7 @@ class RandomEm(object):
     # - optfield : Chances for a field to be optionnal (default 2)
     # @param backend : A backend to use with the new EM
     # @param **kwargs dict : Provide tunable generation parameter
+    # @param cls
     # @return A randomly generate EM
     def random_em(cls, backend=None, **kwargs):
         ed_mod = Model(EmBackendDummy if backend is None else backend)

EditorialModel/types.py

@@ -49,7 +49,9 @@ class EmType(EmComponent):
     ## Create a new EmType and instanciate it
     # @param name str: The name of the new type
     # @param em_class EmClass: The class that the new type will specialize
+    # @param sortcolumn str : The name of the field that will be used to sort
     # @param **em_component_args : @ref EditorialModel::components::create()
+    # @param cls
     # @return An EmType instance
     # @throw EmComponentExistError if an EmType with this name but different attributes exists
     # @see EmComponent::__init__()

leobject/leclass.py

@@ -16,8 +16,8 @@ class LeClass(object):
     _class_id = None
 
     ## @brief Instanciate a new LeClass
-    # @param model Model : The editorial model
-    # @param datasource ? : The datasource
+    # @note Abstract method
+    # @param **kwargs
     def __init__(self, **kwargs):
         raise NotImplementedError("Abstract class")
     

leobject/lefactory.py

@@ -6,7 +6,8 @@ import EditorialModel
 from EditorialModel.model import Model
 from EditorialModel.fieldtypes.generic import GenericFieldType
 
-## @brief The factory that will return LeObject childs instances
+## @brief This class is designed to generated the leobject API given an EditorialModel.model
+# @note Contains only static methods
 #
 # The name is not good but i've no other ideas for the moment
 class LeFactory(object):
@@ -66,12 +67,13 @@ class LeFactory(object):
                 cls_fieldgroup[fieldgroup.name].append(field.name)
         
         return """
+#Initialisation of {name} class attributes
 {name}._fieldtypes = {ftypes}
 {name}._linked_types = {ltypes}
 {name}._fieldgroups = {fgroups}
 """.format(
     name = LeFactory.name2classname(emclass.name),
-    ftypes = "{"+(','.join([ '\n%s:%s'%(repr(f),v) for f,v in cls_fields.items()]))+"}",
+    ftypes = "{"+(','.join([ '\n\t%s:%s'%(repr(f),v) for f,v in cls_fields.items()]))+"\n}",
     ltypes = "{"+(','.join(cls_linked_types))+'}',
     fgroups = repr(cls_fieldgroup)
 )
@@ -94,6 +96,7 @@ class LeFactory(object):
             ))
 
         return """
+#Initialisation of {name} class attributes
 {name}._fields = {fields}
 {name}._superiors = {dsups}
 {name}._leclass = {leclass}
@@ -138,6 +141,8 @@ import %s
             leobj_me_uid[comp.uid] = LeFactory.name2classname(comp.name)
 
         result += """
+## @brief _LeObject concret clas
+# @see leobject::leobject::_LeObject
 class LeObject(_LeObject):
     _model = Model(backend=%s)
     _datasource = %s(**%s)
@@ -151,15 +156,26 @@ class LeObject(_LeObject):
         #LeClass child classes definition
         for emclass in emclass_l:
            result += """
-class %s(LeObject,LeClass):
-    _class_id = %d
-"""%(LeFactory.name2classname(emclass.name), emclass.uid)
+## @brief EmClass {name} LeClass child class
+# @see leobject::leclass::LeClass
+class {name}(LeObject,LeClass):
+    _class_id = {uid}
+""".format(
+    name = LeFactory.name2classname(emclass.name),
+    uid = emclass.uid
+)
         #LeType child classes definition
         for emtype in emtype_l:
            result += """
-class %s(%s,LeType):
-    _type_id = %d
-"""%(LeFactory.name2classname(emtype.name),LeFactory.name2classname(emtype.em_class.name),emtype.uid)
+## @brief EmType {name} LeType child class
+# @see leobject::letype::LeType
+class {name}({leclass},LeType):
+    _type_id = {uid}
+""".format(
+    name = LeFactory.name2classname(emtype.name),
+    leclass = LeFactory.name2classname(emtype.em_class.name),
+    uid = emtype.uid
+)
             
         #Set attributes of created LeClass and LeType child classes
         for emclass in emclass_l:
@@ -169,6 +185,7 @@ class %s(%s,LeType):
 
         #Populating LeObject._me_uid dict for a rapid fetch of LeType and LeClass given an EM uid
         result += """
+## @brief Dict for getting LeClass and LeType child classes given an EM uid
 LeObject._me_uid = %s
 """%repr({ comp.uid:LeFactory.name2classname(comp.name) for comp in emclass_l + emtype_l })
             

leobject/leobject.py

@@ -1,12 +1,19 @@
 #-*- coding: utf-8 -*-
 
-## @package EditorialModel::leobject::leobject
-# @brief Main class to handle objects defined by the types of an Editorial Model
-# an instance of these objects is pedantically called LeObject !
+## @package leobject API to access lodel datas
+#
+# This package contains abstract classes leobject.leclass.LeClass , leobject.letype.LeType, leobject.leobject._LeObject.
+# Those abstract classes are designed to be mother classes of dynamically generated classes ( see leobject.lefactory.LeFactory )
+
+## @package leobject.leobject
+# @brief Abstract class designed to be implemented by LeObject
+#
+# @note LeObject will be generated by leobject.lefactory.LeFactory
 
 import re
 from EditorialModel.types import EmType
 
+## @brief Main class to handle objects defined by the types of an Editorial Model
 class _LeObject(object):
     
     ## @brief The editorial model
@@ -165,7 +172,7 @@ class _LeObject(object):
         return field.startwith('superior.')
     
     ## @brief Check that a relational field is valid
-    # @param fields str : a relational field
+    # @param field str : a relational field
     # @return a nature
     @staticmethod
     def _nature_from_relational_field(field):
@@ -180,6 +187,7 @@ class _LeObject(object):
     ## @brief Check and split a query filter
     # @note The query_filter format is "FIELD OPERATOR VALUE"
     # @param query_filter str : A query_filter string
+    # @param cls
     # @return a tuple (FIELD, OPERATOR, VALUE)
     @classmethod
     def _split_filter(cls, query_filter):

leobject/letype.py

@@ -1,5 +1,15 @@
 #-*- coding: utf-8 -*-
 
+## @package leobject API to access lodel datas
+#
+# This package contains abstract classes leobject.leclass.LeClass , leobject.letype.LeType, leobject.leobject._LeObject.
+# Those abstract classes are designed to be mother classes of dynamically generated classes ( see leobject.lefactory.LeFactory )
+
+## @package leobject.leobject
+# @brief Abstract class designed to be implemented by LeObject
+#
+# @note LeObject will be generated by leobject.lefactory.LeFactory
+
 from Lodel.utils.classinstancemethod import classinstancemethod
 from leobject.leclass import LeClass
 from leobject.leobject import LeObjectError
@@ -64,12 +74,13 @@ class LeType(object):
         pass
     
     ## @brief Delete a LeType from the datasource
-    # @param lodel_id int : The lodel_id identifying the LeType
-    # @param return True if deleted False if not existing
+    # @param lodel_id_l list : List of lodel_id to be deleted
+    # @param cls
+    # @return True if deleted False if not existing
     # @throw InvalidArgumentError if invalid parameters
     # @throw Leo exception if the lodel_id identify an object from another type
     @delete.classmethod
-    def delete(cls, uid_l):
+    def delete(cls, lodel_id_l):
         pass
 
     @classinstancemethod
@@ -118,6 +129,7 @@ class LeType(object):
     ## @brief Check that datas are valid for this type
     # @param datas dict : key == field name value are field values
     # @param complete bool : if True expect that datas provide values for all non internal fields
+    # @param cls
     # @return True if check pass else False
     def check_datas(cls, datas, complete = False):
         try:
@@ -150,7 +162,7 @@ class LeType(object):
     ## @brief Add a superior
     # @param nature str : The raltion nature
     # @param leo LeObject : The superior
-    # @param return True if done False if already done
+    # @return True if done False if already done
     # @throw A Leo exception if trying to link with an invalid leo
     # @throw InvalidArgumentError if invalid argument
     def set_superior(self, nature, leo):