apache / apache/mynewt-documentation

Missing sections in API documentation

Open
#125 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Makefile
Stars
21
Forks
49
PR merge metrics
No merged PRs in 30d

Description

Apparently, there is an issue with doxygen groups (Breathe's `.. doxygengroup::` directive) used for embedding doxygen comments in the documentation.

If there are nested groups in some header file, referencing an outer group in RST file produces documentation only for this explicitly referenced group, excluding nested groups defined in the same scope.

**Example:**
`apache-mynewt-core/kernel/os/include/os/os_cputime.h` contains a group `OSCPUTime` wrapped around the whole file.
In that group there is another one `OSCPUTime_cmp_macros`.
The outcome in [API section ](https://mynewt.apache.org/master/os/core_os/cputime/os_cputime.html#api) is that the macros part is not documented at all.

I tried adding `:inner:` option to the directive, as described [here](https://breathe.readthedocs.io/en/latest/group.html#inner-example), but it did not work.

**Possible fix:**
Either add all groups explicitly to relevant RST files or change doxygen comments directly in header files, adjusting the groups - if possible.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with apache-mynewt-core/kernel/os/include/os/os_cputime.h and the RST source for the os_cputime API section, then inspect how the Breathe `.. doxygengroup::` directive handles the nested OSCPUTime_cmp_macros group. Done means the generated API page documents both the outer OSCPUTime group and its nested macros group.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.