Subject: [lmap] information model documentation style change

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 24 Mar 2015 18:58:20 +0100

Hi,

I am struggling with a lack of descriptions for the information
element definition in the information model. I took the .xml sources
yesterday and I started to rewrite the definitions to make them more
readable and to have sufficient space for explanations. Before I spent
more time on this conversion, I thought I first check for support.
Perhaps a simple example explains this best:

OLD

   // Suppression object to temporarily override new task execution
   // in Instructions and optionally stop currently running tasks

   object {
       boolean             ma-suppression-enabled;
      [boolean             ma-suppression-stop-ongoing-tasks;]
                   // default: false
      [datetime            ma-suppression-start;] // default: immediate
      [datetime            ma-suppression-end;]   // default: indefinite
      [string              ma-suppression-task-names<0..*>;]
                           // default: all tasks if
                           // ma-suppression-task-names is empty
      [string              ma-suppression-schedule-names<0..*>;]
                           // default: all schedules if
                           // ma-suppression-schedule-names is empty
   } ma-suppression-obj;

NEW

3.3.2.  Definition of ma-suppression-obj

     object {
         boolean             ma-suppression-enabled;
        [boolean             ma-suppression-stop-running;]
        [datetime            ma-suppression-start;]
        [datetime            ma-suppression-end;]
        [string              ma-suppression-task-names<0..*>;]
        [string              ma-suppression-schedule-names<0..*>;]
     } ma-suppression-obj;

   The ma-suppression-obj consists of the following elements:

   ma-suppression-enabled:         A boolean indicating whether
                                   suppression is enabled or not.

   ma-suppression-stop-running:    An optional boolean indicating
                                   whether suppression will stop any
                                   running tasks.  The default value for
                                   this boolean is false.

   ma-suppression-start:           The optional date and time when
                                   suppression starts.  The default
                                   value is 'immediate'.

   ma-suppression-end:             The optional date and time when
                                   suppression ends.  The default value
                                   is 'indefinite'.

   ma-suppression-task-names:      An optional and possibly empty
                                   collection of task names.  If not
                                   present, this defaults to all tasks.

   ma-suppression-schedule-names:  An optional and possibly empty
                                   collection of schedule names.  If not
                                   present, this defaults to all
                                   schedules.

In short, I am creating a subsection for each definition (so things
are easier to find), I remove all // inline comments and instead
describe each element/field in plain text below the definition.  The
resulting text is somewhat longer but I find things may more readable
and it provides sufficient space to properly document semantics.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>