[rtems-central commit] rtemsspec: Use @ref for appl config options
Sebastian Huber
sebh at rtems.org
Tue Feb 14 06:49:42 UTC 2023
Module: rtems-central
Branch: master
Commit: 942e8b236ee491ad059ee1cfac3662991738b030
Changeset: http://git.rtems.org/rtems-central/commit/?id=942e8b236ee491ad059ee1cfac3662991738b030
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Tue Feb 14 08:02:57 2023 +0100
rtemsspec: Use @ref for appl config options
The application configuration options are documented in
"cpukit/doxygen/appl-config.h". Since the application configuration
option defines are also present in multiple test program sources, the
"#OPTION" references cannot be mapped to a unique definition. Add an
anchor for each option and reference it to avoid the issues with the
multiple definitions.
---
rtemsspec/applconfig.py | 9 +++++----
rtemsspec/content.py | 5 +++++
rtemsspec/interface.py | 7 ++++---
rtemsspec/tests/test_applconfig.py | 24 +++++++++++++++++++++++-
rtemsspec/tests/test_interface.py | 4 ++--
5 files changed, 39 insertions(+), 10 deletions(-)
diff --git a/rtemsspec/applconfig.py b/rtemsspec/applconfig.py
index 32dd8bd9..54929be5 100644
--- a/rtemsspec/applconfig.py
+++ b/rtemsspec/applconfig.py
@@ -24,11 +24,11 @@
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
from rtemsspec.content import Content, CContent, get_value_double_colon, \
- get_value_doxygen_function, get_value_doxygen_group, get_value_hash, \
- get_value_plural
+ get_value_doxygen_function, get_value_doxygen_group, \
+ get_value_doxygen_ref, get_value_hash, get_value_plural
from rtemsspec.sphinxcontent import GenericContent, SphinxContent, \
SphinxInterfaceMapper
from rtemsspec.items import EmptyItem, Item, ItemCache, ItemGetValueContext, \
@@ -190,6 +190,7 @@ class _DoxygenContentAdaptor(_ContentAdaptor):
def add_option_constraints(self, lines: List[str]) -> None:
self.content.add_brief_description(self._option_type)
+ self.content.add(f"@anchor {self._name}")
self.content.doxyfy(self._description)
self.content.add_paragraph("Default Value", self._default_value)
self.content.add_paragraph("Default Configuration",
@@ -292,7 +293,7 @@ def _get_value_doxygen_unspecfied_type(ctx: ItemGetValueContext) -> Any:
def _add_doxygen_get_values(mapper: ItemMapper) -> None:
for opt in ["feature-enable", "feature", "initializer", "integer"]:
name = f"interface/appl-config-option/{opt}:/name"
- mapper.add_get_value(name, get_value_hash)
+ mapper.add_get_value(name, get_value_doxygen_ref)
mapper.add_get_value("glossary/term:/plural", get_value_plural)
mapper.add_get_value("interface/define:/name", get_value_hash)
mapper.add_get_value("interface/function:/name",
diff --git a/rtemsspec/content.py b/rtemsspec/content.py
index 20c0954e..242e0db9 100644
--- a/rtemsspec/content.py
+++ b/rtemsspec/content.py
@@ -1030,6 +1030,11 @@ def get_value_doxygen_group(ctx: ItemGetValueContext) -> Any:
return f"@ref {ctx.value['identifier']}"
+def get_value_doxygen_ref(ctx: ItemGetValueContext) -> Any:
+ """ Gets a value as a reference for Doxygen markup. """
+ return f"@ref {ctx.value[ctx.key]}"
+
+
def get_value_double_colon(ctx: ItemGetValueContext) -> Any:
""" Gets a value with a :: prefix. """
return f"::{ctx.value[ctx.key]}"
diff --git a/rtemsspec/interface.py b/rtemsspec/interface.py
index d2bb3bf3..d5edc0ec 100644
--- a/rtemsspec/interface.py
+++ b/rtemsspec/interface.py
@@ -35,8 +35,9 @@ from typing import Any, Callable, Dict, Iterator, List, NamedTuple, Optional, \
from rtemsspec.content import CContent, CInclude, enabled_by_to_exp, \
ExpressionMapper, forward_declaration, get_value_compound, \
get_value_double_colon, get_value_doxygen_function, \
- get_value_doxygen_group, get_value_forward_declaration, get_value_hash, \
- get_value_params, get_value_plural, to_camel_case
+ get_value_doxygen_group, get_value_doxygen_ref, \
+ get_value_forward_declaration, get_value_hash, get_value_params, \
+ get_value_plural, to_camel_case
from rtemsspec.items import Item, ItemCache, ItemGetValueMap, ItemMapper
ItemMap = Dict[str, Item]
@@ -87,7 +88,7 @@ class _InterfaceMapper(ItemMapper):
self.add_get_value("interface/variable/doc:/name", get_value_hash)
for opt in ["feature-enable", "feature", "initializer", "integer"]:
name = f"interface/appl-config-option/{opt}/doc:/name"
- self.add_get_value(name, get_value_hash)
+ self.add_get_value(name, get_value_doxygen_ref)
self.add_get_value("interface/unspecified-function/doc:/name",
get_value_doxygen_function)
diff --git a/rtemsspec/tests/test_applconfig.py b/rtemsspec/tests/test_applconfig.py
index fb68ccb1..4c307d36 100644
--- a/rtemsspec/tests/test_applconfig.py
+++ b/rtemsspec/tests/test_applconfig.py
@@ -512,6 +512,8 @@ description m
/**
* @brief This configuration option is a boolean feature define.
*
+ * @anchor a
+ *
* description a
*
* @par Default Configuration
@@ -523,7 +525,7 @@ description m
*
* references:
*
- * * #b
+ * * @ref b
*
* * <a href="unspec-group.html">Unspec Group</a>
*
@@ -555,6 +557,8 @@ description m
/**
* @brief This configuration option is a boolean feature define.
*
+ * @anchor b
+ *
* description b
*
* @par Default Configuration
@@ -568,6 +572,8 @@ description m
/**
* @brief This configuration option is an integer define.
*
+ * @anchor c
+ *
* description c
*
* @par Default Value
@@ -586,6 +592,8 @@ description m
/**
* @brief This configuration option is an integer define.
*
+ * @anchor e
+ *
* description e
*
* @par Default Value
@@ -598,6 +606,8 @@ description m
/**
* @brief This configuration option is an integer define.
*
+ * @anchor f
+ *
* description f
*
* @par Default Value
@@ -610,6 +620,8 @@ description m
/**
* @brief This configuration option is an integer define.
*
+ * @anchor h
+ *
* description h
*
* @par Default Value
@@ -622,6 +634,8 @@ description m
/**
* @brief This configuration option is an integer define.
*
+ * @anchor i
+ *
* description i
*
* @par Default Value
@@ -634,6 +648,8 @@ description m
/**
* @brief This configuration option is an integer define.
*
+ * @anchor j
+ *
* description j
*
* @par Default Value
@@ -649,6 +665,8 @@ description m
/**
* @brief This configuration option is an integer define.
*
+ * @anchor k
+ *
* description k
*
* @par Default Value
@@ -661,6 +679,8 @@ description m
/**
* @brief This configuration option is an initializer define.
*
+ * @anchor l
+ *
* description l
*
* @par Default Value
@@ -683,6 +703,8 @@ description m
/**
* @brief This configuration option is an initializer define.
*
+ * @anchor m
+ *
* description m
*
* @par Default Value
diff --git a/rtemsspec/tests/test_interface.py b/rtemsspec/tests/test_interface.py
index 6a46b837..f6be586b 100644
--- a/rtemsspec/tests/test_interface.py
+++ b/rtemsspec/tests/test_interface.py
@@ -217,8 +217,8 @@ struct Struct;
* @param[in,out] Param3 is parameter 3.
*
* Function description. References to xs, VeryLongFunction(), ::Integer,
- * #Enum, #DEFINE, VERY_LONG_MACRO(), #Variable, ::ENUMERATOR_0, Struct, #a,
- * interface, @ref GroupA, and @ref GroupF. Second parameter is ``Param1``.
+ * #Enum, #DEFINE, VERY_LONG_MACRO(), #Variable, ::ENUMERATOR_0, Struct, @ref
+ * a, interface, @ref GroupA, and @ref GroupF. Second parameter is ``Param1``.
*
* @code
* these two lines
More information about the vc
mailing list