Changed the documentation in the editorial_model.translator.xmlfile module

lodel/editorial_model/translator/xmlfile.py

@@ -11,63 +11,76 @@ LodelContext.expose_modules(globals(), {
         'EmGroup'],
     'lodel.utils.mlstring': ['MlString']})
 
-##@package lodel.editorial_model.translator.xmlfile Translator module designed
-#to load & save EM in XML
+## @package lodel.editorial_model.translator.xmlfile
+# This module is a translator toolkit between and editorial model and an XML file.
 #
-# Structure of a xml file which represents an editorial model:
+# The XML file representing an editorial is composed by several nodes.
+#
+# @par \<name\>
+# The name of the model. It matches with the <b><em>name</em></b> field of the <b><em>EditorialModel class</em></b>
+#
+# @par \<description\>
+# This is the description of a composed element. Inside this node, we can have as many child node as there are languages in which it is translated. \n
+# Each translation is notified by a node, using the following scheme :
 # <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
-#    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 :
-#               <ul><li>\<fre\> for french, 
-#               <li>\<eng\> for english,
-#               <li>\<esp\> for spanish,
-#               <li>\<ger> for german</ul>
-#       <li>\<help_text\> Short explanation of the class's purpose, in different languages, as above
-#       <li>\<abstract\> True or False, field <b><em>abstract</em></b> of the <b><em>EmClass</em></b> 
-#       <li>\<pure_abstract\> True or False, field <b><em>pure_bastract</em></b> of the <b><em>EmClass</em></b>
-#       <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>\<fields\>: set of all the <b><em>EmField</em></b> of the <b><em>EmClass</em></b>\n
-#         for each field: \n
-#           \<field\>
-#               <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
-#               <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
-#    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
-#       <li>\<help_text\> Short explanation of the class's purpose, in different languages, as above
-#       <li>\<requires\> all uids of the <b><em>EmGroups</em></b> required by this group and which are in the fields <b><em>require</em></b>
-#       <li>\<components\> Set of all components of the <b><em>EmGroups</em></b>, representation of the field <b><em>__components</em></b> \n
-#         this item is splitted in two parts :\
-#           <ul><li>\<emfields\> all the emfields with, for each of them:\n
-#               \<emfield\> \n
-#                  <ul><li> \<uid\> <b><em>uid</em></b> of the <b><em>EmField</em></b></ul>
-#           <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>
-
-
-
-
+#   <li><b>\<fre\></b> : french
+#   <li><b>\<eng\></b> : english
+#   <li><b>\<esp\></b> : spanish
+#   <li><b>\<ger\></b> : german
+# </ul>
+#
+# @par \<classes\>
+# This node contains a set of all the <b><em>EmClass</em></b> classes we can find in the model, each represented by a <b>\<class\></b> child node.
+#
+# @par \<class\>
+# It is the representation of a single <b><em>EmClass</em></b> class. It is contained in the <b><em>\<classes\></em></b> node. It contains the following child nodes :
+# <ul>
+# <li><b>\<uid\></b> : The identifier of the class.
+# <li><b>\<display_name\></b> : The class' name, given by the <b><em>display_name</em></b> field of the <b><em>EmClass</em></b> class. This node contains the same language child nodes as the \<description\> node.
+# <li><b>\<help_text\></b> : A short description of the purpose of this class, using the same child nodes for each language, as above.
+# <li><b>\<abstract\></b> : Boolean node, with True or False as values, corresponding to the field <b><em>abstract</em></b> of the <b><em>EmClass</em></b> object.
+# <li><b>\<abstract\></b> : Boolean node, with True or False as values, corresponding to the field <b><em>pure_abstract</em></b> of the <b><em>EmClass</em></b> object.
+# <li><b>\<group\></b> : The unique identifier of the group stored in the <b><em>group</em></b> field of the <b><em>EmClass</em></b> object.
+# <li><b>\<fields\></b> : A set of all the <b><em>EmField</em></b> fields attached to an <b></em>EmClass</em></b> class. Each of them is represented by a <b>\<field\></b> child node.
+# </ul>
+#
+# @par \<field\>
+# This node is the XML representation of an <b><em>EmField</em></b> class. It contains the following child nodes :
+# <ul>
+# <li><b>\<uid\></b> : The identifier of the field.
+# <li><b>\<display_name\></b> : Displayed name, in different languages (same child nodes as above), corresponding to the <b><em>display_name</em></b> property of the <b><em>EmField</em></b>.
+# <li><b>\<help_text\></b> : Short explanation of the purpose of the field, in different languages (one child node for each translation, see above).
+# <li><b>\<group\></b> : <b><em>uid</em></b> of the group of the field <b><em>group</em></b> in the <b><em>EmField</em></b>
+# <li><b>\<datahandler_name\></b> : The name of the datahandler attached to this field (corresponds to the field <b><em>datahandler_name</em></b> of the Emfield)
+# <li><b>\<datahandler_options\></b> : A list of xml items, each of them named with an option name and containing its value
+# </ul>
+#
+# @par \<groups\>
+# This node contains a set of all the groups in the model (represented by <b><em>EmGroup</em></b> objects) with a <b>\<group\></b> child node for each one.
+#
+# @par \<group\>
+# Represents a single group. This node contains the following child nodes :
+# <ul>
+# <li><b>\<uid\></b> : unique id of the <b><em>EmField</em></b>.
+# <li><b>\<display_name\></b> : Corresponds to the <b><em>display_name</em></b>  property of the <b><em>EmField</em></b>, in different languages (see above)
+# <li><b>\help_text\></b> : Short explanation of the group's purpose, in different languages (see above)
+# <li><b>\<requires\></b> : All the unique identifiers of the <b><em>EmGroups</em></b> required by this group and which are in the fields <b><em>require</em></b>.
+# <li><b>\<components\></b> : A set of all components of the <b><em>EmGroups</em></b>, representation of the field <b><em>__components</em></b>. This node is splitted in two parts :
+#     <ul>
+#         <li><b>\<emfields\></b> : all the emfields with, for each of them:\n
+#               <b>\<emfield\></b> \n
+#                  <b>\<uid\></b> : <b><em>uid</em></b> of the <b><em>EmField</em></b>
+#           <li><b>\<emclasses\></b> : all the emclasses with, for each of them:\n
+#               <b>\<emclass\></b> \n
+#                  <b>\<uid\></b> : <b><em>uid</em></b> of the <b><em>EmClass</em></b>
+#     </ul>
+# </ul>
 
 
-##@brief Saves a model in a xml file
+## @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 : additional options.
+#                     - 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')
@@ -100,19 +113,19 @@ def save(model, **kwargs):
         outfile.close()
     
     
-##@brief Writes a representation of a MlString in xml
-# @param etree : the xml object
-# @param elem : the element which represents a MlString
-# @param mlstr : the mlstr to write
+## @brief Writes a representation of a MlString in XML
+# @param etree Element : the XML object
+# @param elem Element : the element which represents a MlString
+# @param mlstr MlString: the mlstr to write
 def write_mlstring_xml(etree, elem, mlstr):
     for lang in mlstr.values:
         ss_mlstr = etree.SubElement(elem,lang)
         ss_mlstr.text = mlstr.get(lang)
         
-##@brief Writes the definition of a datahandler in xml
+## @brief Writes the definition of a datahandler in xml
 # @param etree : the xml object
-# @param elem : the element which defines a datahandler
-# @param dhdl_name : the name of the datahandler
+# @param elem Element : the element which defines a datahandler
+# @param dhdl_name str : the name of the datahandler
 # @param kwargs : the options of the datahandler
 def write_datahandler_xml(etree, elem, dhdl_name, **kwargs):
     dhdl = etree.SubElement(elem,'datahandler_name')
@@ -138,15 +151,15 @@ def write_datahandler_xml(etree, elem, dhdl_name, **kwargs):
                     opt_val = str(argu)
         arg.text = opt_val
         
-##@brief Writes a representation in xml of a EmField
+## @brief Writes a representation in xml of a EmField
 # @param etree : the xml object
-# @param elem : the element for the EmField
-# @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 elem Element: the element for the EmField
+# @param uid str : the uid of the EmField
+# @param name str : the name of the field
+# @param help_text MlString: explanations of the EmField
+# @param group str|None: the uid of a group, can be None
+# @param datahandler_name str: Name of the datahandler attached to the field
+# @param **kwargs dict : 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')
@@ -169,10 +182,12 @@ 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 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 elem Element : the element for the EmGroup
+# @param uid str : the uid of the EmGroup
+# @param name str : the name of the group
+# @param help_text MlString : explanations of the EmGroup
+# @param requires list : a list of the group's uids whose this group depends
+# @param components list : a list of the EmComponent objects contained in the group
 def write_emgroup_xml(etree, elem, uid, name, help_text, requires, components):
     emgroup = etree.SubElement(elem, 'group')
     emgroup_uid = etree.SubElement(emgroup, 'uid')
@@ -204,15 +219,16 @@ def write_emgroup_xml(etree, elem, uid, name, help_text, requires, components):
             em_group_comp_cls_ins = etree.SubElement(emgroup_comp_cls, 'emclass')
             em_group_comp_cls_ins.text = component.uid
 
-##@brief Writes a representation of a EmClass in xml
-# @param etree : the xml object
-# @param elem : the element for the EmClass
-# @param name  : the name of the group
-# @param help_text : explanations of the EmClass
-# @param fields : a dict
-# @param parents : a list of EmClass uids
-# @param abstract : a boolean
-# @param pure_abstract : a boolean
+## @brief Writes a representation of a EmClass in XML
+# @param etree : the XML object
+# @param elem Element : the element for the EmClass
+# @param uid str : the unique identifier of the EmClass
+# @param name str : the name of the group
+# @param help_text MlString : explanations of the EmClass
+# @param fields dict : a dict representing all the fields of the class
+# @param parents list : a list of the EmClass uids of this class' parents
+# @param abstract bool : a boolean
+# @param pure_abstract bool : a boolean
 def write_emclass_xml(etree, elem, uid, name, help_text, group, fields, parents, abstract = False, pure_abstract = False):
     emclass = etree.SubElement(elem, 'class')
     emclass_uid  = etree.SubElement(emclass, 'uid')
@@ -244,11 +260,10 @@ def write_emclass_xml(etree, elem, uid, name, help_text, group, fields, parents,
     emclass_parents = etree.SubElement(emclass, 'parents')
     emclass_parents.text = ",".join(parents_list)
 
-##@brief Loads a model from a xml file
-# @param model EditorialModel : the model to load
+## @brief Loads a model from a XML file
+# @param filename str : The file from which the editorial model will be loaded
 # @return a new EditorialModel object
 def load(filename):
-
     Em = etree.parse(filename)
     emodel = Em.getroot()
     name = emodel.find('name')
@@ -270,9 +285,10 @@ def load(filename):
             grp = model.add_group(grp)
     return model
 
-##@brief Creates a EmClass from a xml description
-# @param elem : the element which represents the EmClass
-# @param model  : the model which will contain the new class
+
+## @brief Creates a EmClass from a xml description
+# @param model EditorialModel : the model which will contain the new class
+# @param elem Element: the element which represents the EmClass
 # @return a new EmClass object
 def load_class_xml(model, elem):
     uid = elem.find('uid').text
@@ -332,11 +348,11 @@ def load_class_xml(model, elem):
             
     return emclass
     
-##@brief Creates a EmField from a xml description
-#@param elem : the element which represents the EmField
-#@param model  : the model which will contain the new field
-#@param emclass EmClass : the EmClass of the field
-#@return a new EmField object
+## @brief Creates a EmField from a XML description
+# @param model EditorialModel: the model which will contain the new field
+# @param elem Element : the element which represents the EmField
+# @param emclass EmClass : the EmClass of the field
+# @return a new EmField object
 def load_field_xml(model, elem, emclass):
     uid = elem.find('uid').text
     if elem.find('display_name').text is None:
@@ -369,10 +385,11 @@ def load_field_xml(model, elem, emclass):
     
     return emfield
 
-##@brief Returns datahandler options from a xml description
-# @param elem : the element which represents the datahandler
-# @param model  : the model which will contain the new field
-# @return datahandler options
+
+## @brief Returns datahandler options from a XML description
+# @param elem Element : the element which represents the datahandler
+# @param model EditorialModel : the model which will contain the new field
+# @return dict
 def load_dhdl_options_xml(model, elem):
     dhdl_options=dict()
     for opt in elem:
@@ -396,10 +413,10 @@ def load_dhdl_options_xml(model, elem):
     return dhdl_options
              
     
-##@brief Creates a EmGroup from a xml description
-# @param elem : the element which represents the EmGroup
-# @param model  : the model which will contain the new group
-# @return a new EmGroup object
+## @brief Creates a EmGroup from a XML description
+# @param model EditorialModel : the model which will contain the new group
+# @param elem Element : the element which represents the EmGroup
+# @return EmGroup
 def load_group_xml(model, elem):
     uid = elem.find('uid')
     
@@ -450,10 +467,9 @@ def load_group_xml(model, elem):
     group.add_components(comp)     
     return group
 
-##@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
+## @brief Constructs a MlString from a XML description
+# @param elem Element : the element which represents the MlString
+# @return MlString
 def load_mlstring_xml(elem):
     mlstr = dict()
     for lang in elem: