apache / apache/celix

Incorrect usage of @section in Doxygen documentation?

Open
#680 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C
Stars
193
Forks
99
Avg merge
1m
Merged PRs (30d)
1

Description

There is the following warning in section command's [documentation](https://www.doxygen.nl/manual/commands.html#cmdsection):

> This command only works inside related page documentation and not in other documentation blocks!

In our coding convention, it is recommended to be used for error codes documentation:

- If a function can return multiple error codes, use a errors section (`@section errors_section Errors`) to document the
possible errors. Use `man 2 write` as an example for a good errors section.

I found one usage of `@section` in `celix_threads.h`, and checked our online [documentation](https://nightlies.apache.org/celix/2.4.0/). Unfortunately, utils library is not included in the documentation.
I'm not sure whether the current usage is correct and can produce the intended documentation.

PS: Currently I am working on Celix documentation translation so that it can be used for some internal training program in my day job. I'll go back to this issue after the translation is complete.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.