Separato "interno" dalla documentazione "esterna" in doxygen

Question

Voglio documentare una libreria con doxygen. La documentazione verrà letta da due classi di persone: gli utenti interessati esclusivamente all'API esterna e agli sviluppatori che desiderano visualizzare la documentazione per tutte le funzioni/strutture.

Vorrei utilizzare per separare doxyfiles per creare la documentazione. C'è qualche "tag" che posso inserire in un blocco di commenti per contrassegnare un commento come interno/esterno?

Answer 1

Set INTERNAL_DOCS:

# The INTERNAL_DOCS tag determines if documentation 
# that is typed after a \internal command is included. If the tag is set 
# to NO (the default) then the documentation will be excluded. 
# Set it to YES to include the internal documentation. 

INTERNAL_DOCS   = NO 

Nella documentazione, è possibile utilizzare \internal o @internal a qualsiasi granularità che volete (file, funzione, ecc).

Answer 2

Utilizzare il comando \ cond:

\internal (@internal) ha solo granularità per il blocco commento corrente. Non ti consente alcun modo per nascondere una definizione di struttura in C.

Il modo più semplice per farlo è mettere

\ cond INTERNO

nella parte superiore di un file di intestazione interna e

\ endcond

in basso. Poi, nel file di configurazione, si aggiunge

ENABLED_SECTIONS = INTERNO

per consentire le voci interne di essere inclusi nella documentazione.

Questo modo è consigliato anche dagli utenti di Doxygen, ad es. here

Answer 3

Questa è una soluzione semplice che si avvale del fatto che in genere è possibile distinguere le parti interne ed esterne del codice in file.

Si può semplicemente limitare i file di input per solo i file di intestazione che si desidera esporre nella documentazione esterna:

# For internal, we parse all files 
INPUT = ./ 
# For external, we parse only the files containing the public interface 
INPUT = include/header1.hpp include/header2.hpp 

Questo ha il vantaggio che i file di origine non devono essere modificati (con \internal o @internal).