[rtems-docs commit] eng: Generalize external references
Sebastian Huber
sebh at rtems.org
Fri May 19 05:21:25 UTC 2023
Module: rtems-docs
Branch: master
Commit: 5928d04c84f0b88eaeae2a686dc207885b7c6d09
Changeset: http://git.rtems.org/rtems-docs/commit/?id=5928d04c84f0b88eaeae2a686dc207885b7c6d09
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Sep 24 15:00:51 2021 +0200
eng: Generalize external references
Use a common subtype for external references of interfaces and
requirements. Add specializations for document and file references.
Update #3715.
---
eng/req/items.rst | 178 +++++++++++++++++++++++++++++++++++-------------------
1 file changed, 115 insertions(+), 63 deletions(-)
diff --git a/eng/req/items.rst b/eng/req/items.rst
index d60bd7d..6b2f91b 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -1575,7 +1575,8 @@ name
unspecified interface.
references
- The attribute value shall be an :ref:`SpecTypeInterfaceReferencesSet`.
+ The attribute value shall be a list. Each list element shall be an
+ :ref:`SpecTypeExternalReference`.
.. _SpecTypeInterfaceVariableItemType:
@@ -1619,8 +1620,8 @@ rationale
then it shall state the rationale or justification of the requirement.
references
- The attribute value shall be a list. Each list element shall be a
- :ref:`SpecTypeRequirementReference`.
+ The attribute value shall be a list. Each list element shall be an
+ :ref:`SpecTypeExternalReference`.
requirement-type
The attribute value shall be a :ref:`SpecTypeName`. It shall be the
@@ -2182,6 +2183,10 @@ method
The attribute value shall be a :ref:`SpecTypeRequirementValidationMethod`.
Validation by test is done through :ref:`SpecTypeTestCaseItemType` items.
+references
+ The attribute value shall be a list. Each list element shall be an
+ :ref:`SpecTypeExternalReference`.
+
text
The attribute value shall be a string. It shall provide the validation
evidence depending on the validation method:
@@ -3693,6 +3698,71 @@ Please have a look at the following example:
- RTEMS_NETWORKING
- not: RTEMS_SMP
+.. _SpecTypeExternalDocumentReference:
+
+External Document Reference
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeExternalReference` through the ``type``
+attribute if the value is ``document``. It specifies a reference to a document.
+
+All explicit attributes shall be specified. The explicit attributes for this
+type are:
+
+name
+ The attribute value shall be a string. It shall be the name of the
+ document.
+
+.. _SpecTypeExternalFileReference:
+
+External File Reference
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeExternalReference` through the ``type``
+attribute if the value is ``file``. It specifies a reference to a file.
+
+All explicit attributes shall be specified. The explicit attributes for this
+type are:
+
+hash
+ The attribute value shall be a :ref:`SpecTypeSHA256HashValue`. It shall be
+ the SHA256 hash value of the content of the referenced file.
+
+.. _SpecTypeExternalReference:
+
+External Reference
+^^^^^^^^^^^^^^^^^^
+
+This set of attributes specifies a reference to some object external to the
+specification. All explicit attributes shall be specified. The explicit
+attributes for this type are:
+
+identifier
+ The attribute value shall be a string. It shall be the type-specific
+ identifier of the referenced object. For *group* references use the Doxygen
+ group identifier. For *file* references use a file system path to the
+ file.
+
+type
+ The attribute value shall be a :ref:`SpecTypeName`. It shall be the type of
+ the referenced object.
+
+This type is refined by the following types:
+
+* :ref:`SpecTypeExternalDocumentReference`
+
+* :ref:`SpecTypeExternalFileReference`
+
+* :ref:`SpecTypeGenericExternalReference`
+
+This type is used by the following types:
+
+* :ref:`SpecTypeInterfaceUnspecifiedItemType`
+
+* :ref:`SpecTypeRequirementItemType`
+
+* :ref:`SpecTypeRequirementValidationItemType`
+
.. _SpecTypeFunctionImplementationLinkRole:
Function Implementation Link Role
@@ -3704,6 +3774,33 @@ role of links. It is used to indicate that a
:ref:`SpecTypeFunctionalRequirementItemType` item specifies parts of the
function.
+.. _SpecTypeGenericExternalReference:
+
+Generic External Reference
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the following types:
+
+* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
+ is ``define``
+
+* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
+ is ``function``
+
+* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
+ is ``group``
+
+* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
+ is ``macro``
+
+* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
+ is ``url``
+
+* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
+ is ``variable``
+
+It specifies a reference to an object of the specified type.
+
.. _SpecTypeGlossaryMembershipLinkRole:
Glossary Membership Link Role
@@ -4333,20 +4430,6 @@ value is ``interface-placement``. It defines the interface placement role of
links. It is used to indicate that an interface definition is placed into an
interface container, for example a header file.
-.. _SpecTypeInterfaceReferencesSet:
-
-Interface References Set
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-This set of attributes defines references for the interface. Generic attributes
-may be specified. Each generic attribute key shall be a :ref:`SpecTypeName`.
-Each generic attribute value shall be a string. The key defines the reference
-kind. The value shall be a kind-specific reference target.
-
-This type is used by the following types:
-
-* :ref:`SpecTypeInterfaceUnspecifiedItemType`
-
.. _SpecTypeInterfaceReturnDirective:
Interface Return Directive
@@ -4486,14 +4569,14 @@ This type is used by the following types:
* :ref:`SpecTypeBuildOptionSetTestStateAction`
+* :ref:`SpecTypeExternalReference`
+
* :ref:`SpecTypeFunctionalRequirementItemType`
* :ref:`SpecTypeGlossaryItemType`
* :ref:`SpecTypeInterfaceItemType`
-* :ref:`SpecTypeInterfaceReferencesSet`
-
* :ref:`SpecTypeLink`
* :ref:`SpecTypeNonFunctionalRequirementItemType`
@@ -4553,50 +4636,6 @@ value is ``placement-order``. This link role defines the placement order of
items in a container item (for example an interface function in a header file
or a documentation section).
-.. _SpecTypeRequirementReference:
-
-Requirement Reference
-^^^^^^^^^^^^^^^^^^^^^
-
-This set of attributes specifies a requirement reference. All explicit
-attributes shall be specified. The explicit attributes for this type are:
-
-identifier
- The attribute value shall be a string. It shall be the type-specific
- identifier of the reference target. For *group* references use the Doxygen
- group identifier.
-
-type
- The attribute value shall be a :ref:`SpecTypeRequirementReferenceType`.
-
-This type is used by the following types:
-
-* :ref:`SpecTypeRequirementItemType`
-
-.. _SpecTypeRequirementReferenceType:
-
-Requirement Reference Type
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The value shall be a string. It specifies the type of a requirement reference.
-The value shall be an element of
-
-* "``define``",
-
-* "``file``",
-
-* "``function``",
-
-* "``group``",
-
-* "``macro``", and
-
-* "``variable``".
-
-This type is used by the following types:
-
-* :ref:`SpecTypeRequirementReference`
-
.. _SpecTypeRequirementRefinementLinkRole:
Requirement Refinement Link Role
@@ -4879,6 +4918,19 @@ This type is used by the following types:
* :ref:`SpecTypeRuntimePerformanceRequirementItemType`
+.. _SpecTypeSHA256HashValue:
+
+SHA256 Hash Value
+^^^^^^^^^^^^^^^^^
+
+The value shall be a string. It shall be a SHA256 hash value encoded in
+base64url. The value shall match with the regular expression
+"``^[A-Za-z0-9+_=-]{44}$``".
+
+This type is used by the following types:
+
+* :ref:`SpecTypeExternalFileReference`
+
.. _SpecTypeSPDXLicenseIdentifier:
SPDX License Identifier
More information about the vc
mailing list