doc: add alias for properties of functions #25411
Conversation
Use @prop to describe function properries. In both doxygen and RST docs this will appear as a note. Signed-off-by: Anas Nashif <anas.nashif@intel.com>
|
example (The text in there is a placeholder, no suggestion on the wording is being made here):
|
| ALIASES = "rst=\verbatim embed:rst:leading-asterisk" \ | ||
| "endrst=\endverbatim" | ||
| ALIASES = "rst=\verbatim embed:rst:leading-asterisk" "endrst=\endverbatim" | ||
| ALIASES += "prop=\note @b Properties: @b" |
There was a problem hiding this comment.
Should the alias be named funcprop instead? That is what we decided here:
#21061 (comment)
There was a problem hiding this comment.
why do you need func in here? we have param, not funcparam, brief, not funcbrief! I think @prop should be enough and function is implied.
There was a problem hiding this comment.
Doxygen also already has @property which does something different and could confuse people.
There was a problem hiding this comment.
I think we should use a unequivocal name that is exclusive to zephyr to avoid any potential clashes. Hence the funcprop proposal that we settled on last week.
There was a problem hiding this comment.
I don't see any problem with this, but it doesn't address the more fundamental issue of how the annotation is to be done in the source code. For k_sleep() that might be:
@funcprop sleep
or
@funcprop sleep reschedule
depending on whether the implicit properties are made explicit.
Depending on what we want the annotation to look like in the code, how it gets processed by the documentation generation, and what it looks like = in the generated documentation, a section like this may or may not be appropriate. If use of a @note alias requires putting the property tags on a separate line so they don't confuse Doxygen IMO this is not a great solution.
|
This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time. |
Use @prop to describe function properries. In both doxygen and RST docs
this will appear as a note.
Fixes #21061