Fixing some doxygen comments errors

DataSource/MySQL/fieldtypes.py

@@ -17,6 +17,7 @@ import EditorialModel.fieldtypes.leo
 
 ## @brief Returns column specs from fieldtype
 # @param emfieldtype EmFieldType : An EmFieldType insance
+# @param noauto_inc bool : if True don't set the autoincrement parameter
 # @todo escape default value
 def singlevaluefieldtype_db_init_specs(emfieldtype, noauto_inc = False):
     colspec = ''
@@ -46,6 +47,7 @@ def singlevaluefieldtype_db_init_specs(emfieldtype, noauto_inc = False):
 #  - the second tuple item is a tuple(key_name, key_value)
 #  - the third tuple item is a tuple(column_type, column_spec)
 # @param fieldtype GenericFieldType : A FieldType instance
+# @param noauto_inc bool : if True don't set the autoincrement parameter
 # @return a tuple (instruction_type, infos)
 def fieldtype_db_init(fieldtype, noauto_inc = False):
     if isinstance(fieldtype, EditorialModel.fieldtypes.rel2type.EmFieldType):

DataSource/MySQL/leapidatasource.py

@@ -38,8 +38,13 @@ class LeDataSourceSQL(DummyDatasource):
     ## @brief select lodel editorial components using given filters
     # @param target_cls LeCrud(class): The component class concerned by the select (a LeCrud child class (not instance !) )
     # @param field_list list: List of field to fetch
-    # @param filters list: List of filters (see @ref lecrud_filters)
-    # @param rel_filters list: List of relational filters (see @ref lecrud_filters)
+    # @param filters list: List of filters (see @ref api_user_side)
+    # @param rel_filters list: List of relational filters (see @ref api_user_side)
+    # @param group list of tupple: List of column to group together.  group = [('titre', 'ASC'), ]
+    # @param order list of tupple : List of column to order.  order = [('titre', 'ASC'), ]
+    # @param offset int : Used with limit to choose the start row
+    # @param limit int : Number of row to be returned
+    # @param instanciate bool : If True return an instance, else return a dict
     # @return a list of LeCrud child classes
     # @todo this only works with LeObject.get(), LeClass.get() and LeType.get()
     # @todo for speed get rid of all_to_dicts
@@ -209,10 +214,8 @@ class LeDataSourceSQL(DummyDatasource):
     ## @brief update ONE existing lodel editorial component
     # @param target_cls LeCrud(class) : Instance of the object concerned by the update
     # @param lodel_id : id of the component
-    # @param rel_filters list : List of relationnal filters (see @ref leobject_filters)
     # @param **datas : Datas in kwargs
     # @return the number of updated components
-    # @todo implement other filters than lodel_id
     def update(self, target_cls, lodel_id, **datas):
 
         # it is a LeType
@@ -390,7 +393,7 @@ class LeDataSourceSQL(DummyDatasource):
 
     ## @brief Sets a new rank on a relation
     # @param le_relation LeRelation
-    # @param new_rank int: integer representing the absolute new rank
+    # @param rank int: integer representing the absolute new rank
     # @return True if success, False if failure
     # TODO Conserver cette méthode dans le datasource du fait des requêtes SQL. Elle est appelée par le set_rank de LeRelation
     def update_rank(self, le_relation, rank):

DataSource/MySQL/migrationhandler.py

@@ -46,6 +46,8 @@ class MysqlMigrationHandler(DummyMigrationHandler):
     ## @brief Construct a MysqlMigrationHandler
     # @param module : sql module
     # @param conn_args dict : A dict containing connection options
+    # @param db_engine str : Name of a MySQL db engine (default is InnoDB, don't change it ! ;) ) 
+    # @param **kwargs : arguement given to the module.connect() method
     def __init__(self, module=pymysql, conn_args=None, db_engine='InnoDB', **kwargs):
         # Database connection
         self._dbmodule = module
@@ -74,6 +76,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
     # @param uid int : The uid of the change EmComponent
     # @param initial_state dict | None : dict with field name as key and field value as value. Representing the original state. None mean creation of a new component.
     # @param new_state dict | None : dict with field name as key and field value as value. Representing the new state. None mean component deletion
+    # @param engine str : Mysql db engine, should be "InnoDB"
     # @throw EditorialModel.exceptions.MigrationHandlerChangeError if the change was refused
     def register_change(self, em, uid, initial_state, new_state, engine=None):
         if engine is None:
@@ -114,7 +117,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
     ## @brief Add a relationnal field
     # Add a rel2type attribute
     # @note this function handles the table creation
-    # @param em Model : EditorialModel.model.Model instance
+    # @param edmod Model : EditorialModel.model.Model instance
     # @param rfuid int : Relationnal field uid
     def add_relationnal_field(self, edmod, rfuid):
         emfield = edmod.component(rfuid)
@@ -146,7 +149,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
     #
     # Delete a rel2type attribute
     # @note this method handles the table deletion
-    # @param em Model : EditorialModel.model.Model instance
+    # @param edmod Model : EditorialModel.model.Model instance
     # @param rfuid int : Relationnal field uid
     def del_relationnal_field(self, edmod, rfuid):
         emfield = edmod.component(rfuid)
@@ -165,7 +168,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
             self._generate_triggers(tname, self._r2type2cols(edmod, r2tf))
 
     ## @brief Given an EmField uid add a column to the corresponding table
-    # @param em Model : A Model instance
+    # @param edmod Model : A Model instance
     # @param uid int : An EmField uid
     def add_col_from_emfield(self, edmod, uid):
         emfield = edmod.component(uid)
@@ -180,8 +183,9 @@ class MysqlMigrationHandler(DummyMigrationHandler):
         self._generate_triggers(tname, cols_l)
 
     ## @brief Given a class uid create the coressponding table
-    # @param em Model : A Model instance
+    # @param edmod Model : A Model instance
     # @param uid int : An EmField uid
+    # @param engine str : Db engine (should be "InnoDB")
     def create_emclass_table(self, edmod, uid, engine):
         emclass = edmod.component(uid)
         if not isinstance(emclass, EditorialModel.classes.EmClass):
@@ -199,7 +203,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
             self._add_fk(table_name, utils.common_tables['object'], pkname, pkname)
 
     ## @brief Given an EmClass uid delete the corresponding table
-    # @param em Model : A Model instance
+    # @param edmod Model : A Model instance
     # @param uid int : An EmField uid
     def delete_emclass_table(self, edmod, uid):
         emclass = edmod.component(uid)
@@ -214,7 +218,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
         self._query("""DROP TABLE {table_name};""".format(table_name=tname))
 
     ## @brief Given an EmField delete the corresponding column
-    # @param em Model : an @ref EditorialModel.model.Model instance
+    # @param edmod Model : an @ref EditorialModel.model.Model instance
     # @param uid int : an EmField uid
     def delete_col_from_emfield(self, edmod, uid):
         emfield = edmod.component(uid)
@@ -244,7 +248,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
         self._query("""ALTER TABLE {table_name} DROP COLUMN {col_name};""".format(table_name=tname, col_name=fname))
 
     ## @brief Construct a table name given a rela2type EmField instance
-    # @param em Model : A Model instance
+    # @param edmod Model : A Model instance
     # @param emfield EmField : An EmField instance
     # @return a table name
     def _r2t2table_name(self, edmod, emfield):
@@ -253,7 +257,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
         return utils.r2t_table_name(emclass.name, emtype.name)
 
     ## @brief Generate a columns_fieldtype dict given a rel2type EmField
-    # @param em Model : an @ref EditorialModel.model.Model instance
+    # @param edmod Model : an @ref EditorialModel.model.Model instance
     # @param emfield EmField : and @ref EditorialModel.fields.EmField instance
     def _r2type2cols(self, edmod, emfield):
         return {f.name: f.fieldtype_instance() for f in edmod.components('EmField') if f.rel_field_id == emfield.uid}
@@ -316,7 +320,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
     # @param pk_ftype fieldtype | tuple : pk fieldtype (give a tuple for multi pk)
     # @param engine str : The engine to use with this table
     # @param charset str : The charset of this table
-    # @param if_exist str : takes values in ['nothing', 'drop']
+    # @param if_exists str : takes values in ['nothing', 'drop']
     # @param noauto_inc bool : if True forbids autoincrement on PK
     def _create_table(self, table_name, pk_name, pk_ftype, engine, charset='utf8', if_exists='nothing', noauto_inc = False):
         #Escaped table name
@@ -359,6 +363,7 @@ class MysqlMigrationHandler(DummyMigrationHandler):
     # @param col_name str : The columns name
     # @param col_fieldtype EmFieldype the fieldtype
     # @param relation bool | None : a flag to indicate if we add a column in a table linked with an bject or with a relation (used only when the column is MultiValueFieldType )
+    # @param drop_if_exists bool : if True delete the column before re-adding it
     # @return True if the column was added else return False
     def _add_column(self, table_name, col_name, col_fieldtype, drop_if_exists=False, relation=False):
         instr, col_type, col_specs = fieldtypes_utils.fieldtype_db_init(col_fieldtype)
@@ -437,6 +442,7 @@ ADD COLUMN {col_name} {col_type} {col_specs};"""
     # @param ref_table_name str : Referenced table name
     # @param key_infos tuple : tuple(key_name, key_fieldtype)
     # @param column_infos tuple : tuple(col_name, col_fieldtype)
+    # @param relation bool : pass True if concern a LeRelation or False of concern a LeObject
     def _add_column_multivalue(self, ref_table_name, key_infos, column_infos, relation):
         key_name, key_ftype = key_infos
         col_name, col_ftype = column_infos
@@ -481,6 +487,7 @@ ADD COLUMN {col_name} {col_type} {col_specs};"""
     # @param dst_table_name str : The name of the table the FK will point on
     # @param src_col_name str : The name of the concerned column in the src_table
     # @param dst_col_name str : The name of the concerned column in the dst_table
+    # @param fk_name str|None : The foreign key name, if None the name will be generated (not a good idea)
     def _add_fk(self, src_table_name, dst_table_name, src_col_name, dst_col_name, fk_name=None):
         stname = utils.escape_idname(src_table_name)
         dtname = utils.escape_idname(dst_table_name)
@@ -507,6 +514,7 @@ ON UPDATE CASCADE;""".format(
     ## @brief Given a source and a destination table, delete the corresponding FK
     # @param src_table_name str : The name of the table where the FK is
     # @param dst_table_name str : The name of the table the FK point on
+    # @param fk_name str|None : the foreign key name, if None try to guess it
     # @warning fails silently
     def _del_fk(self, src_table_name, dst_table_name, fk_name=None):
         if fk_name is None:
@@ -543,11 +551,12 @@ DROP FOREIGN KEY {fk_name}""".format(
     #
     # Primarly designed to create trigger for DATETIME types
     # The method generates triggers of the form
-    #
-    # CREATE TRIGGER BEFORE <moment> ON <table_name>
-    # FOR EACH ROW SET <for colname, colval in cols_val>
-    # NEW.<colname> = <colval>,
-    # <endfor>;
+    # <pre>
+    # CREATE TRIGGER BEFORE &lt;moment&gt; ON &lt;table_name&gt;
+    # FOR EACH ROW SET lt;for colname, colval in &lt;cols_val&gt;
+    # NEW.lt;colname> = lt;colval&gt;,
+    # lt;endfor&gt;;
+    # </pre>
     # @param table_name str : The table name
     # @param moment str : can be 'update' or 'insert'
     # @param cols_val dict : Dict with column name as key and column value as value
@@ -618,6 +627,7 @@ FOR EACH ROW SET {col_val_list};""".format(
         self.db_conn.commit()  # autocommit
 
     ## @brief Given a common field name return an EmFieldType instance
+    # @param cls
     # @param cname str : Common field name
     # @return An EmFieldType instance
     @classmethod

DataSource/MySQL/utils.py

@@ -51,7 +51,8 @@ def get_fk_name(src_table_name, dst_table_name):
 
 
 ## @brief Exec a query
-# @param query str : SQL query
+# @param connection : Db connection (has returned by dbmodule.connect())
+# @param query_string str : SQL query
 def query(connection, query_string):
     if Settings.debug_sql:
         print("SQL : ", query_string)

DataSource/dummy/leapidatasource.py

@@ -13,12 +13,14 @@ class DummyDatasource(object):
 
     ## @brief select lodel editorial components given filters
     # @param target_cls LeCrud(class) : The component class concerned by the insert (a LeCrud child class (not instance !) )
+    # @param field_list list : List of field names we want in the returned value or instance
     # @param filters list : List of filters (see @ref leobject_filters )
     # @param rel_filters list : List of relationnal filters (see @ref leobject_filters )
     # @param group list of tupple: List of column to group together.  group = [('titre', 'ASC'), ]
     # @param order list of tupple : List of column to order.  order = [('titre', 'ASC'), ]
     # @param limit int : Number of row to be returned
     # @param offset int : Used with limit to choose the start row
+    # @param instanciate bool : If True return an instance, else return a dict
     # @return a list of LeCrud child classes
     def select(self, target_cls, field_list, filters, rel_filters=None, order=None, group=None, limit=None, offset=0, instanciate=True):
         pass

EditorialModel/fieldtypes/format.py

@@ -9,7 +9,9 @@ class EmFieldType(char.EmFieldType):
 
     ## @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, max_length, **kwargs):
         self._field_list = field_list
         self._format_string = format_string

EditorialModel/fieldtypes/generic.py

@@ -17,6 +17,7 @@ class GenericFieldType(object):
     ## @brief Generic constructor for fieldtypes 
     # @param internal False | str : define wheter or not a field is internal
     # @param immutable bool : indicate if the fieldtype has to be defined in child classes of LeObject or if it is defined globally and immutable
+    # @param **args
     # @throw NotImplementedError if called from bad class
     def __init__(self, internal = False, immutable = False, **args):
         if self.__class__ == GenericFieldType:
@@ -62,7 +63,7 @@ class GenericFieldType(object):
         raise RuntimeError("Unable to construct data for field %s", fname)
 
     ## @brief Check datas consistency
-    # @param leo LeCrud : A LeCrud child class instance
+    # @param lec LeCrud : A LeCrud child class instance
     # @param fname str : The field name
     # @param datas dict : dict storing fields values
     # @return an Exception instance if fails else True
@@ -134,6 +135,7 @@ class ReferenceFieldType(SingleValueFieldType):
     # @param nullable bool : is None allowed as value ?
     # @param unique bool : Indicate if a field should handle uniq value
     # @param primary bool : If True the field is a primary key
+    # @param internal str|False : if False the field is not internal. Else can be 'autosql' or 'internal'
     # @param **args : Other arguments
     # @throw NotImplementedError if called from bad class
     def __init__(self, reference, internal=False, nullable = True, uniq = False, primary = False, **args):
@@ -161,6 +163,8 @@ class MultiValueFieldType(GenericFieldType):
     # @param keyname str : The identifier key name
     # @param key_fieldtype SingleValueFieldType : A SingleValueFieldType child class instance
     # @param value_fieldtype SingleValueFieldType : A SingleValueFieldType child class instance
+    # @param internal str|False : if False the field is not internal. Else can be 'autosql' or 'internal'
+    # @param **args
     def __init__(self, keyname, key_fieldtype, value_fieldtype, internal = False, **args):
         super().__init__(internal)
         ## stores the keyname

Lodel/settings.py

@@ -126,11 +126,11 @@ Settings = SettingsHandler()
 # from Lodel.settings import Settings
 # if Settings.debug:
 #   print("DEBUG")
-# #or
+# # or
 # if Settings.get('debug'):
 #   print("DEBUG")
 # Settings.debug = False
-# #or
+# # or
 # Settings.set('debug', False)
 # </pre>
 #