-
Notifications
You must be signed in to change notification settings - Fork 6.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add support for setting function properties using Doxygen #32972
Add support for setting function properties using Doxygen #32972
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't have an opinion on whether this is adequate for Zephyr's needs, but it's a reasonable first step.
https://github.com/pabigot/zephyr/commits/pr/32972 has two fixup commits that complete the terminology set and the proposed effect on the api in #18970 (comment)
222826c
to
a5da6b8
Compare
dev-review (Apr 1):
|
a5da6b8
to
dd62ef2
Compare
Add aliases for setting function properties. A function may have 0, one or more function properties. Example usage: @funcprops \isr_ok, \async These aliases will translate to API Terminology references when Doxygen is rendered on Sphinx. On the Doxygen side they will just translate to plain text. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Replace old notes marking ISR safe functions with the recently introduced funcprops. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
dd62ef2
to
0dc2e88
Compare
Updated PR:
|
@nashif @carlescufi ping |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if it is possible to have a brief "pop-up" description when you hover over the properties.
Afaik this is not trivial to do, would require a Sphinx plugin at least. |
Current approach
This PR is an attempt to resolve #21061 by using Doxygen aliases. Developer can add a list of function properties by using
@funcprops \prop1, ..., \propN
. They will be rendered as plain text in the Doxygen build and a with a link to terminology on the Sphinx side. Note that this solution does not allow to obtain a list of, e.g. "all functions that are async".Doxygen output:
Sphinx output:
Pros: Minimal changes, standardized keywords, renders links on the Sphinx side
Cons: Plain-text on the Doxygen side, not possible to list functions with a certain property
Other options
Links to terminology in both Doxygen and Sphinx
In order to achieve this functionality the
terminology.rst
content needs to be moved to a Doxygen page. Then, theALIAS
can contain, e.g.@ref async
. The content of the Doxygen page can be rendered back in Sphinx using the recently added..doxygenpage
directive inbreathe
, together with breathe-doc/breathe#645.Doxygen output:
Sphinx output:
Pros: Function properties contain link to terminology in both, Doxygen and Sphinx.
Cons: Terminology has to be moved to Doxygen
List of functions with a certain property
In order to obtain a list of functions that have a certain property, e.g.
async
I have tried the options listed below. Note that I haven't had success in obtaining a fully functional solution.\xrefitem
Using
\xrefitem <key> "(heading)" "(list title)" { text }
a new page is created in the Doxygen side with a list of all functions that have the property set. One of the problems is that the generated page is added to the root of the Doxygen tree. Furthermore, I haven't been able to make this option work reliably when multiple properties are used.Doxygen:
Sphinx:
Pros: Pages with a list of all functions with a certain property are generated
Cons: Not working properly on the Sphinx side (renders empty), page location can't be controlled in the Doxygen side
\ingroup
The advantage of using groups is that pages location can be controlled (e.g. creating a parent group somewhere in the hierarchy). However, the function will be listed in only one group, so it is not an option.
From Doxygen documentation:
Pros: None
Cons: Does not work when multiple properties are used.
Table of properties
In order to generate something like:
I haven't found a solution using existing Doxygen/Sphinx/Breathe facilities. On the Doxygen side we should have conditionals to evaluate certain properties of a function. As fas as I know, this is not possible. Onthe Sphinx side we need to implement a new custom plugin that parses Doxygen XML files and generates such table. It may be possible to re-use
breathe
parser, but I'm not sure it it is worth for this purpose due to its "complexity".