Spexygen Reference Manual 3.0.0
Spexygen Reference Manual 3.0.0
Spexygen↑ is a Doxygen↑ extension for creating traceable technical specifications, such as:
The main objectives and features of Spexygen are:
Traceability is the cornerstone of any formal documentation system, especially those intended for managing functional safety. It enables product teams to associate every work artifact (e.g., a specific requirement) with all the related project artifacts (e.g., design, code, or tests), both backward and forward. Traceability enables everyone to see how every work artifact relates to the requirement — and vice versa — at any point during development. This ability fosters team collaboration and enables early detection of possible production risks.
The diagram below illustrates the kinds of traceability and the relationships between them. The downstream work artifacts establish backward-traceability to the related upstream artifact by means of the explicitly provided Unique Identifiers (UIDs).
Backward traceability begins at a specific work artifact and links it to the original artifact. For example, architecture element can be linked with an upstream requirement, or code artifact with the upstream design. Backward traceability gives visibility into why specific artifacts were created and how different pieces of a system fit together. Tracing in this way also allows testers to find gaps or missing work artifacts.
Forward traceability begins at the original artifact and links it with all the resulting forward work items. For example, a requirement can be linked with source code elements that implement that requirement. This type of trace ensures that each original artifact (e.g., requirement) is not only satisfied but verified and validated. In the Spexygen documentation the forward traceability is generated automatically by the spexygen.py Python script.
Bidirectional traceability is the ability to perform both forward and backward traceability. Bidirectional traceability is the optimal type of traceability because it gives teams full visibility from requirements through architecture, design, source code, tests, and back again. The system implemented in the Spexygen documentation provides such bidirectional traceability.
Traceability is enabled by the consistent use of Unique Identifiers (UIDs), which are short text labels associated with all work artifacts, such as requirements, architecture elements, design elements, source code elements, coding standard deviations, tests, functional safety documents, etc.
The most important feature of UIDs is their uniqueness within the whole system under consideration. To avoid name conflicts, it is advantageous to establish general rules for constructing the UIDs. Throughout Spexygen documentation, the UIDs have the hierarchical structure consisting of fields separated by underscores and/or dashes:
+------------------ [1] Work artifact type (e.g., 'SRS' for Software
| Requirement Specification)
| +--------------- [2] Component unique identifier (e.g, 'QP' for QP Framework)
| | +----------- [3] Work artifact ID (abbreviation or number)
| | | +-------- [4] Work artifact number
| | | | +---- [5] Optional variant letter ('A', 'B', 'C'...)
| | | | |+--- [6] Optional version number (1, 2, 3...)
| | | | ||
SRS_xx_yyy_zz[-A2]
Examples:
The various fields in the UID are as follows:
[1] the UID starts with a field corresponding to the document type. This helps to immediately identify the document where the UID is defined. Here are some suggestions for the document types:
[2] the Component Unique Identifier (CUI) denotes the component addressed by this UID, which should be unique enough to avoid name conflicts with other software components in a larger system (e.g., whole application). Here are some examples of component IDs, but the intent is to extend this list to other components as well:
[3] the "Work artifact kind" field identifies the kind of the artifact. Its meaning is local to the document type in field [1]: each document that defines item-level UIDs specifies its own set of artifact-kind tokens in its own "UID structure"/"Document Conventions" subsection. Here are some suggestions for UID kinds:
[4] "Work artifact group" field identifies the aspect of the work artifact. This is the most flexible part in the UID to accommodate other existing conventions, such as MISRA deviations, the work artifact group field should be easily identifiable with the MISRA Rule/Directive ID, such as D04_01 for "Directive 4.1", or R10_04 for "Rule 10.4". Still, please note that the more structured UID convention of using two-digits for feature groups (e.g., D04_10 instead of D4_10) provide additional benefits, such as correct order under a simple alphabetical sort. This property is missing in the original MISRA IDs (e.g., a simple alphabetical sort will place Rule 10.8 before Rule 8.10).
[5] "Work artifact number" field distinguishes the artifact within the group, or when no group is used, within the artifact kind.
[6] optionally, the UID might contain a variant letter ('A', 'B', 'C',...)
Alternatively, UIDs of code elements follow the rules established by Doxygen, with the following general form:
+-------------- [1] Namespace (e.g., class or module)
| +--- [2] element (e.g., attribute or operation)
| |
[namespace]_[element]
Examples: