Documentare un concetto C++ usando doxygen?

Question

Esiste un modo conveniente per documentare un concetto C++ in doxygen? Mi piacerebbe avere una sorta di documentazione come this in the boost documentation.

Answer 1

Quello che puoi fare è definire un tag personalizzato chiamato Concept, che puoi usare come descrivi. Un example di questo è quello di utilizzare il meccanismo di alias in Doxygen, qualcosa come:

ALIAS + = "con = \ xrefitem con \" Concept \ "\ "Concetti \""

Answer 2

È possibile utilizzare \tparam per commentare/documentare su template parameters.

Answer 3

Attualmente uso pagine di manuale separati per documentare concetti e raggrupparli con \section e \subsection. Posso quindi collegarli a loro con \ref. Questo funziona fintanto che descrivi concetti con le tabelle come nel link che hai dato, ma sfortunatamente non abiliterà i collegamenti alle singole sezioni.

Ho anche un alias per creare un elenco di concetti che un tipo modella.

Answer 4

Dopo aver lottato con Doxygen, sono finalmente arrivato alla seguente soluzione.

1. definire un gruppo per il vostro concetto: utilizzando le pagine non è così appropriata dal momento che una pagina dovrebbe indicare le sue sottopagine (dall'alto verso il basso della struttura), mentre i gruppi indicano potenzialmente molti gruppi di genitori. Questo permette:

   • Aggiunta di un concetto di uno (o più) concetto genitore (s), senza modificare il concetto madre stessa (affinamento/generalizzazione dei concetti)
   • Collegamento un'entità a diversi concetti, senza cambiare la concetto stesso (ad es. quando si aggiunge una classe alla libreria attuazione di un concetto specifico)

   esempio

   /*!@defgroup measurement_functor_concepts Measurement function objects 
   * @ingroup generalconcepts 
   * @{ 
   * @par Description 
   * blablabla 
   * 
   * @par Notations 
   * Let @c F be the type of the function object, @c f an instance. 
   * 
   * @par Valid Expressions 
   * - @c f function object is ... 
   * - <b>f.result()</b> returns ... 
   * @} 
   */ 
   

2. Definire un comando personalizzato concept con un argomento:

   ALIASES += concept{1}="@ingroup \1\n@par Implemented concepts:\n@ref \1" 
   

   Il comando:

   • include l'entità nel gruppo che definisce il concetto: apparirà l'entità nella documentazione del concetto (l'entità possono apparire in diversi gruppi)
   • aggiunge un paragrafo con Implemented concepts che fornisce un collegamento al concetto implementato.

3. indicare che una particolare classe/struct implementa il concetto:

   //!@brief Does things... 
   //!@concept{measurement_functor_concepts} 
   template <class T> 
   struct my_struct: public std::unary_function<T, void> {}; 
   

non ho trovato un modo per generare una bella documentazione come in Boost (bei tavolini per l'espressione valida, ecc.), ma almeno questa organizzazione della documentazione separa le cose correttamente.

Answer 5

vi consiglio di considerare quanto segue:

a) Guardate la documentazione per il concetto Boost Controllo biblioteca. Questa documentazione mostra come creare una classe che può essere utilizzata nel codice per verificare che a livello di tipo soddisfi effettivamente i requisiti del concetto che si desidera definire. Si utilizza in questo modo:

template<typename T> 
my_class{ 
    MyConcept(T); // provokes compile error if T does not match concept 
    T m_t; 
}; 

FYI c'è una corrispondenza uno a uno tra gli elementi utilizzati per la creazione della classe concetto di controllo e ed i concetti proposta lite. Quindi, quando i concetti in realtà funzionano, la transizione dovrebbe essere facile.

b) Ora utilizzare DOxygen per documentare la classe di controllo MyConcept !!!

c) Uso Doxygen/tparam su my_class documentazione per riferirsi a MyConcept

c) Così ora avete esattamente quello che stai chiedendo !!! - una pagina separata per il tuo concetto e la possibilità di farvi riferimento da tutta la classe che richiede quel concetto.