20 |
20 |
21 Standalone documents like this design document and the user guide are documented in reStructuredText__ format. |
21 Standalone documents like this design document and the user guide are documented in reStructuredText__ format. |
22 |
22 |
23 __ http://docutils.sourceforge.net/rst.html |
23 __ http://docutils.sourceforge.net/rst.html |
24 |
24 |
25 HTML documentation is generated in ``/helium/build/doc`` using the ``hlm doc`` command. |
25 HTML documentation is generated in ``/helium/build/doc`` using the ``hlm docs`` command. |
|
26 |
|
27 API documentation |
|
28 ----------------- |
|
29 |
|
30 The Helium API documentation is generated directly from the Ant source files. Additional documentation for Ant objects (properties, targets, macros, etc) and special markup is defined in a similar style to JavaDoc, following these conventions: |
|
31 |
|
32 * Additional documentation is written as XML comments. |
|
33 * Typically the preceeding comment for an Ant object is assumed to relate to that object. A comment can be definitively noted as a Ant documentation comment by adding a ``*`` character at the start. |
|
34 |
|
35 * Project comments must have the ``*`` character in order to avoid assuming that the copyright comment block is project documentation:: |
|
36 |
|
37 <!--* comment text --> |
|
38 |
|
39 * The text format of the documentation can be formatted in MediaWiki format. |
|
40 * The first sentence of the comment is taken as the summary for short text fields. The rest of the text is the full documentation. |
|
41 * Specific metadata tags are defined using ``@``. Each tag should be on a newline and all tags should be after the general documentation paragraphs:: |
|
42 |
|
43 <!--* comment text |
|
44 |
|
45 @scope private |
|
46 --> |
|
47 |
|
48 * A number of tags are supported: |
|
49 |
|
50 .. csv-table:: Ant comment tags |
|
51 :header: "Tag", "Applies to", "Description" |
|
52 |
|
53 "scope", "All elements", "The scope or visibility of the element. Valid values are ``public`` (default), ``protected`` and ``private``." |
|
54 "editable", "All types", "Whether this element should be overridden or defined by the user. Valid values are ``required`` and ``optional``" |
|
55 "type", "Properties", "The type of the property value. Valid values are ``string`` (default), ``integer``, ``boolean``." |
|
56 "deprecated", "All elements", "Documents that the element is deprecated and may be removed in a future release. The text should describe what to use instead." |
|
57 |
|
58 * Some properties (and other types) are only defined by the user, so there is no default declaration inside Helium. These can be documented completely within a comment:: |
|
59 |
|
60 <!--* @property name.of.property |
|
61 This property must be defined by the user. |
|
62 |
|
63 @scope public |
|
64 @editable required |
|
65 @type integer |
|
66 --> |
26 |
67 |
27 |
68 |
28 .. index:: |
69 .. index:: |
29 single: Index References-creating |
70 single: Index References-creating |
30 |
71 |
72 All documentation related to Helium. Files are in .rst format (HTML versions can be generated under ``/build/doc`` using the ``hlm doc`` command). |
113 All documentation related to Helium. Files are in .rst format (HTML versions can be generated under ``/build/doc`` using the ``hlm doc`` command). |
73 |
114 |
74 ``/external`` |
115 ``/external`` |
75 Applications and libraries that are maintained outside of the Helium team. |
116 Applications and libraries that are maintained outside of the Helium team. |
76 |
117 |
77 ``/testconfig`` |
|
78 Test build configurations. |
|
79 |
|
80 ``/tests`` |
118 ``/tests`` |
81 Test data for unit tests. All unit tests are co-located with the code under test. |
119 Test data for unit tests. All unit tests are co-located with the code under test. |
82 |
120 |
83 ``/tools`` |
121 ``/tools`` |
84 A number of subdirectories for each stage of the build. Each directory may contain Ant scripts and other tools and scripts related to that stage. |
122 A number of subdirectories for each stage of the build. Each directory may contain Ant scripts and other tools and scripts related to that stage. |
104 hlm-jar.bat |
142 hlm-jar.bat |
105 |
143 |
106 can be run from the ``/helium`` directory. This will update the ``nokia_ant.jar`` file in ``/tools/common/java/lib``. |
144 can be run from the ``/helium`` directory. This will update the ``nokia_ant.jar`` file in ``/tools/common/java/lib``. |
107 |
145 |
108 Each custom task must be defined inside the ``antlib.xml`` file inside ``/tools/common/java/src/nokia/ant``. |
146 Each custom task must be defined inside the ``antlib.xml`` file inside ``/tools/common/java/src/nokia/ant``. |
109 |
|
110 |
|
111 .. index:: |
|
112 single: XML Schemas |
|
113 |
|
114 XML schemas |
|
115 =========== |
|
116 |
|
117 A ``validate-xml`` command can be run to check the various Helium XML files against their schema (this is run in the automated unit tests). |
|
118 |
|
119 There are schema files for these XML file types: |
|
120 |
|
121 * Helium data model. |
|
122 |
|
123 |
|
124 .. index:: |
|
125 single: Helium Data Model |
|
126 |
|
127 Helium data model |
|
128 ================= |
|
129 |
|
130 The Helium data model defines the configuration elements needed to configure Helium. It is defined in the file ``/config/helium_data_model.xml`` and contains: |
|
131 |
|
132 * A list of configuration elements with metadata: |
|
133 |
|
134 * Name. Defines the name of the configuration element. Required. |
|
135 * Type. Defines the type of the configuration element, i.e. if the configuration element is a string, integer, boolean or flag. Required. |
|
136 * Usage. Defines the typical usage of the property. Must one of "must", "recommended", "allowed", "discouraged", "never". Required. |
|
137 * Description. This should be in .rst format. Required. |
|
138 * Deprecated. This is a optional element that defines the property is deprecated. |
|
139 |
|
140 * A list of groups that group together related configuration elements and their usage requirements within that group, i.e. if that feature is to be used, what configuration is required and what is optional. All required configuration elements in a group must be defined. |
|
141 |
|
142 Any Ant configuration can be checked against the model by running ``hlm check``. |
|
143 |
147 |
144 |
148 |
145 .. index:: |
149 .. index:: |
146 single: Assertions |
150 single: Assertions |
147 |
151 |