rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-15 17:57:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

eng: Unify interface function and macro

Browse Source 
This allows the documentation of parameter and return types for macros.

Update #3715.
This commit is contained in:
Sebastian Huber 2022-10-04 08:29:18 +02:00
parent 889a498dbb
commit c812323f0f
1 changed files with 66 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
eng/req/items.rst
View File

@ -87,14 +87,12 @@ The specification item types have the following hierarchy:
* :ref:`SpecTypeInterfaceForwardDeclarationItemType` * :ref:`SpecTypeInterfaceForwardDeclarationItemType`
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
* :ref:`SpecTypeInterfaceGroupItemType` * :ref:`SpecTypeInterfaceGroupItemType`
* :ref:`SpecTypeInterfaceHeaderFileItemType` * :ref:`SpecTypeInterfaceHeaderFileItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceTypedefItemType`
* :ref:`SpecTypeInterfaceUnspecifiedItemType` * :ref:`SpecTypeInterfaceUnspecifiedItemType`
@ -1145,14 +1143,12 @@ This type is refined by the following types:
* :ref:`SpecTypeInterfaceForwardDeclarationItemType` * :ref:`SpecTypeInterfaceForwardDeclarationItemType`
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
* :ref:`SpecTypeInterfaceGroupItemType` * :ref:`SpecTypeInterfaceGroupItemType`
* :ref:`SpecTypeInterfaceHeaderFileItemType` * :ref:`SpecTypeInterfaceHeaderFileItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceTypedefItemType`
* :ref:`SpecTypeInterfaceUnspecifiedItemType` * :ref:`SpecTypeInterfaceUnspecifiedItemType`
@ -1405,29 +1401,35 @@ with the :ref:`SpecTypeInterfaceTargetLinkRole` to an
:ref:`SpecTypeInterfaceCompoundItemType` item. This link defines the type :ref:`SpecTypeInterfaceCompoundItemType` item. This link defines the type
declared by the forward declaration. declared by the forward declaration.
.. _SpecTypeInterfaceFunctionItemType: .. _SpecTypeInterfaceFunctionOrMacroItemType:
Interface Function Item Type Interface Function or Macro Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This type refines the :ref:`SpecTypeInterfaceItemType` through the This type refines the following types:
``interface-type`` attribute if the value is ``function``. This set of
attributes specifies a function. All explicit attributes shall be specified. * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
The explicit attributes for this type are: the value is ``function``
* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
the value is ``macro``
This set of attributes specifies a function or a macro. All explicit attributes
shall be specified. The explicit attributes for this type are:
brief brief
The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
definition definition
The attribute value shall be an The attribute value shall be an
:ref:`SpecTypeInterfaceFunctionDefinitionDirective`. :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`.
description description
The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
name name
The attribute value shall be a string. It shall be the name of the The attribute value shall be a string. It shall be the name of the function
function. or macro.
notes notes
The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
@ -1491,39 +1493,6 @@ prefix
path to the header file in the interface domain. For example path to the header file in the interface domain. For example
:file:`cpukit/include`. :file:`cpukit/include`.
.. _SpecTypeInterfaceMacroItemType:
Interface Macro Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^
This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``macro``. This set of attributes
specifies a macro. All explicit attributes shall be specified. The explicit
attributes for this type are:
brief
The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
definition
The attribute value shall be an
:ref:`SpecTypeInterfaceDefinitionDirective`.
description
The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
name
The attribute value shall be a string. It shall be the name of the macro.
notes
The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
params
The attribute value shall be a list. Each list element shall be an
:ref:`SpecTypeInterfaceParameter`.
return
The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`.
.. _SpecTypeInterfaceTypedefItemType: .. _SpecTypeInterfaceTypedefItemType:
Interface Typedef Item Type Interface Typedef Item Type
@ -3729,14 +3698,12 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceEnumeratorItemType` * :ref:`SpecTypeInterfaceEnumeratorItemType`
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
* :ref:`SpecTypeInterfaceGroupItemType` * :ref:`SpecTypeInterfaceGroupItemType`
* :ref:`SpecTypeInterfaceHeaderFileItemType` * :ref:`SpecTypeInterfaceHeaderFileItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceTypedefItemType`
* :ref:`SpecTypeInterfaceVariableItemType` * :ref:`SpecTypeInterfaceVariableItemType`
@ -3929,8 +3896,6 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceEnumeratorItemType` * :ref:`SpecTypeInterfaceEnumeratorItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceTypedefItemType`
* :ref:`SpecTypeInterfaceVariableItemType` * :ref:`SpecTypeInterfaceVariableItemType`
@ -3986,12 +3951,10 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceEnumeratorItemType` * :ref:`SpecTypeInterfaceEnumeratorItemType`
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
* :ref:`SpecTypeInterfaceGroupItemType` * :ref:`SpecTypeInterfaceGroupItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceParameter` * :ref:`SpecTypeInterfaceParameter`
* :ref:`SpecTypeInterfaceReturnValue` * :ref:`SpecTypeInterfaceReturnValue`
@ -4047,7 +4010,7 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceEnabledByExpression` * :ref:`SpecTypeInterfaceEnabledByExpression`
* :ref:`SpecTypeInterfaceFunctionDefinitionVariant` * :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`
.. _SpecTypeInterfaceEnumDefinitionKind: .. _SpecTypeInterfaceEnumDefinitionKind:
@ -4077,10 +4040,21 @@ This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-enumerator``. It defines the interface enumerator role of value is ``interface-enumerator``. It defines the interface enumerator role of
links. links.
.. _SpecTypeInterfaceFunctionDefinition: .. _SpecTypeInterfaceFunctionLinkRole:
Interface Function Definition Interface Function Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-function``. It defines the interface function role of
links. It is used to indicate that a :ref:`SpecTypeActionRequirementItemType`
item specifies functional requirements of an
:ref:`SpecTypeInterfaceFunctionOrMacroItemType` item.
.. _SpecTypeInterfaceFunctionOrMacroDefinition:
Interface Function or Macro Definition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A value of this type shall be of one of the following variants: A value of this type shall be of one of the following variants:
@ -4109,52 +4083,55 @@ A value of this type shall be of one of the following variants:
performed. performed.
return return
The attribute value shall be a string. It shall be the function return The attribute value shall be an optional string. If the value is present,
type. On the return type a context-sensitive substitution of item then it shall be the function return type. On the return type a
variables is performed. context-sensitive substitution of item variables is performed.
* There may be no value (null). * There may be no value (null).
This type is used by the following types: This type is used by the following types:
* :ref:`SpecTypeInterfaceFunctionDefinitionDirective` * :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`
* :ref:`SpecTypeInterfaceFunctionDefinitionVariant` * :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`
.. _SpecTypeInterfaceFunctionDefinitionDirective: .. _SpecTypeInterfaceFunctionOrMacroDefinitionDirective:
Interface Function Definition Directive Interface Function or Macro Definition Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This set of attributes specifies a function definition directive. All explicit This set of attributes specifies a function or macro definition directive. All
attributes shall be specified. The explicit attributes for this type are: explicit attributes shall be specified. The explicit attributes for this type
are:
default default
The attribute value shall be an :ref:`SpecTypeInterfaceFunctionDefinition`. The attribute value shall be an
The default definition will be used if no variant-specific definition is :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. The default definition
enabled. will be used if no variant-specific definition is enabled.
variants variants
The attribute value shall be a list. Each list element shall be an The attribute value shall be a list. Each list element shall be an
:ref:`SpecTypeInterfaceFunctionDefinitionVariant`. :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`.
This type is used by the following types: This type is used by the following types:
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
.. _SpecTypeInterfaceFunctionDefinitionVariant: .. _SpecTypeInterfaceFunctionOrMacroDefinitionVariant:
Interface Function Definition Variant Interface Function or Macro Definition Variant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This set of attributes specifies a function definition variant. All explicit This set of attributes specifies a function or macro definition variant. All
attributes shall be specified. The explicit attributes for this type are: explicit attributes shall be specified. The explicit attributes for this type
are:
definition definition
The attribute value shall be an :ref:`SpecTypeInterfaceFunctionDefinition`. The attribute value shall be an
The definition will be used if the expression defined by the ``enabled-by`` :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. The definition will be
attribute evaluates to true. In generated header files, the expression is used if the expression defined by the ``enabled-by`` attribute evaluates to
evaluated by the C preprocessor. true. In generated header files, the expression is evaluated by the C
preprocessor.
enabled-by enabled-by
The attribute value shall be an The attribute value shall be an
@ -4162,19 +4139,7 @@ enabled-by
This type is used by the following types: This type is used by the following types:
* :ref:`SpecTypeInterfaceFunctionDefinitionDirective` * :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`
.. _SpecTypeInterfaceFunctionLinkRole:
Interface Function Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-function``. It defines the interface function role of
links. It is used to indicate that a :ref:`SpecTypeActionRequirementItemType`
item specifies functional requirements of an
:ref:`SpecTypeInterfaceFunctionItemType` or a
:ref:`SpecTypeInterfaceMacroItemType` item.
.. _SpecTypeInterfaceGroupIdentifier: .. _SpecTypeInterfaceGroupIdentifier:
@ -4248,9 +4213,7 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceEnumeratorItemType` * :ref:`SpecTypeInterfaceEnumeratorItemType`
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceTypedefItemType`
@ -4276,9 +4239,7 @@ name
This type is used by the following types: This type is used by the following types:
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceTypedefItemType`
@ -4353,9 +4314,7 @@ A value of this type shall be of one of the following variants:
This type is used by the following types: This type is used by the following types:
* :ref:`SpecTypeInterfaceFunctionItemType` * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
* :ref:`SpecTypeInterfaceMacroItemType`
* :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceTypedefItemType`