apache / apache/celix

Incorrect usage of @section in Doxygen documentation?

Aperta
#680 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
C
Stelle
193
Fork
99
Merge medio
1m
PR unite (30g)
1

Descrizione

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.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

Inizia leggendo l’uso di @section in celix_threads.h e confrontalo con la documentazione del comando section di Doxygen. Verifica se la libreria utils e la relativa documentazione generata includono la sezione errors prevista. Il lavoro è completato quando si è determinato se l’uso è valido e lo si è documentato o corretto, se necessario.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
c
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.