Preparing Spexygen Documentation

Working with SpexygenGenerating Spexygen Documentation

As described in the spexygen workflow, Spexygen works with the documentation and annotated code prepared according to the Doxygen conventions. However, Spexygen provides a layer of customized commands for defining traceable "work artifacts", which can be of two kinds:

1. work artifacts created in pure documentation, such as requirements specification; and
2. code artifacts created by Doxygen for various elements of source code, such as classes, functions, macros, etc.

Defining Work Artifacts

Work artifacts (e.g., requirements) are defined by means of the following Spexygen custom commands:

Command	Purpose
@uid{uid,brief}	starts the definition of a work artifact parameter: uid — the UID of the work artifact parameter: brief — brief description of the work artifact
@uid_litem{title}	adds new line - item in the work artifact definition parameter: title — Title of the line item(e.g., Details)
@uid_bw_trace{brief}	adds the backward trace section in in the work artifact definition parameter: brief — request Spexygen to add the brief item description
@uid_bw_trace	adds the backward trace section in in the work artifact definition overloaded version without requesting the brief description
@uid_fw_trace{levels}	adds the forward trace section in in the work artifact definition this is a request to Spexygen to generate the recursive forward traceability for the work artifact optional parameter: levels truncates the displayed recursion levels
@enduid	ends the definition work artifact must be placed at the end of work artifact definition
@tr{uid}	references the given UID parameter: uid — the UID of the work artifact

Remarks

The Spexygen custom commands are defined as ALIAS=... in Spexyfile.

The following snippet illustrates how a work artifact (a requirement) has been documented for Spexygen (see also file srs.dox):

[1] @section srs_req Requirements
    ...
[2] @uid{SRS_PRJ_Foo_03,My project class Foo shall provide a verify operation.}
[3] @uid_litem{Description}
    Longer description of the requirement
[4] @uid_bw_trace{brief}
[5] - @tr{SRS_PRJ_Foo_00}
[6] @uid_fw_trace{2}
[7] @enduid

[1] Spexygen "work artifacts" must be defined in the scope of a Doxygen @section.

[2] each work artifact is defined with the Spexygen command @uid{}, which takes two arguments:

1. the UID associated with the artifact (e.g., SRS_PRJ_Foo_03)
2. the brief description of the artifact (e.g., My project class Foo shall provide a verify operation.)

   Attention

   The whole @uid{} command must be defined in a single line of text and the brief description must not contain commas ,

[3] the work artifact definition can contain "line items", such as "Description" coded by means of the @uid_litem{Description} Spexygen command. A work artifact can have multiple line items defined with the @uid_litem{} Spexygen command.

[4] the work artifact can specify backward traceability by means of the @uid_bw_trace Spexygen command. If this command provides argument {brief}, Spexygen will generate the brief description for each of the provided traceability links (see the next step [5])

[5] the traceability links to the upstream artifacts must be provided explicitly by means of the @tr{uid} Spexygen command. The command establishes traceability to the UID provided in the argument (e.g., SRS_PRJ_Foo_00)

[6] the work artifact can specify forward traceability by means of the @uid_fw_trace Spexygen command

Note

The @uid_fw_trace Spexygen command is just a placeholder for Spexygen to generate the forward traceability links at this place. The optional parameter truncates the number of recursion levels to the specified value.

[7] The artifact definition must end with the Spexygen @enduid command

The following screen shot shows how the work artifact defined in the code snipped above is rendered in HTML:

Examples of "work artifacts" (requirements)

Defining Code Artifacts

Code artifacts (e.g., functions, macros, classes) are naturally handled by Doxygen and the Spexygen system must comply with the exiting Doxygen conventions. The "code artifacts" are defined by means of the following Spexygen custom commands:

Command	Purpose
@code_uid{uid,brief}	starts the definition of a code artifact parameter: uid — the UID of the code artifact parameter: brief — brief description of the code artifact
@code_litem{item}	adds new line-item in the code artifact definition parameter: title — Title of the line item(e.g., Details)
@code_bw_trace{brief}	adds the backward trace section in in the code artifact definition parameter: brief — request Spexygen to add the brief item description
@code_bw_trace	adds the backward trace section in in the code artifact definition overloaded version without requesting the brief description
@code_fw_trace{levels}	adds the forward trace section in in the code artifact definition this is a request to Spexygen to generate the recursive forward traceability for the code artifact optional parameter: levels truncates the displayed recursion levels
@endcode_uid	ends the definition code artifact must be placed at the end of code artifact definition
@tr{uid}	references the given UID parameter: uid — the UID of the code artifact

Remarks

The Spexygen custom commands are defined as ALIAS=... in Spexyfile.

The following snippet illustrates how a code artifact (function free_fun()) has been documented (see also file header.h):

    /*!
[1] @code_uid{Foo_verify_(), Operation verify_() of class Foo brief description}
[2] @code_litem{Details}
    Operation verify_() of class Foo longer description.

    @param[in]  me - the instance pointer (OOP in C)

[3] @code_bw_trace{brief}
[4] - @tr{SRS_PRJ_Foo_03}
[5] @code_fw_trace{3}
[6] @endcode_uid
    */
[7] bool Foo_verify_(Foo const* const me);

[1] each code artifact is defined with the Spexygen command @code_uid{}, which takes two arguments :

1. the UID associated with the artifact(e.g., Foo_verify_())
2. the brief description of the artifact(e.g., Operation verify_() of class Foo brief description)

   Attention

   The whole @code_uid{} command must be defined in a single line of text and the brief description must not contain commas ,

[2] the code artifact definition can contain "line items", such as "Details" coded by means of the @code_litem{Details} Spexygen command. A code artifact can have multiple items defined with the @code_litem{...} Spexygen command.

[3] the code artifact can specify backward traceability by means of the @uid_bw_trace Spexygen command. If this command provides argument {brief}, Spexygen will generate the brief description for each of the provided traceability links(see the next step [4])

[4] the traceability links to the upstream artifacts must be provided explicitly by means of the @tr{uid} Spexygen command. The command establishes traceability to the UID provided in the argument(e.g., SRS_PRJ_Foo_03)

[5] the code artifact can specify forward traceability by means of the @code_fw_trace Spexygen command

Note

The @code_fw_trace Spexygen command is just a placeholder for Spexygen to generate the forward traceability links at this place. The optional parameter truncates the number of recursion levels to the specified value.

[6] The code artifact definition must end with the Spexygen @endcode_uid command

[7] Finally, the code artifact needs to be declared, so that Doxygen can analyze the syntax of the specific programming language.

The following screen shot shows how the code artifact defined in the code snipped above is rendered in HTML :

Examples of "code artifacts" (function)

Working with SpexygenGenerating Spexygen Documentation