Il generatore di documentazione Doxygen permette di segnare un pezzo di commento come attenzione, nota, osservazione, todo o avvertimento.Scegliere tra l'attenzione, nota, osservazione, todo e di allarme in Doxygen
Quali linee guida devo seguire per classificare correttamente un commento come uno di essi?
Tutti questi tag sono utilizzati allo scopo di evidenziare una sezione della documentazione come particolarmente notevole, rispetto ad altre sezioni che non sono così contrassegnate. Sono tutti utilizzati per attirare l'attenzione del lettore sul paragrafo contrassegnato.
Nota è il tag più generico ed è quello da utilizzare nella maggior parte dei casi in cui si desidera che il lettore "prenda nota" della questione descritta nella sezione.
Il Attenzione tag può essere utilizzato per evidenziare una nota particolarmente importante, uno che non si desidera che il lettore a trascurare.
Il tag deve essere usato al posto di Attenzione quando ci possono essere conseguenze negative da considerare se il lettore non sta attento nel modo in cui usa l'oggetto documentato.
Il Osservazioni e Osservazioni tag possono essere utilizzati per le note che hanno minore importanza. Se vuoi descrivere qualcosa in un senso "oh, a proposito", il tag Remark è utile per questo.
Il tag Todo è utilizzato in modo diverso rispetto agli altri elencati. Viene solitamente utilizzato per indicare che il codice descritto nel commento ha uno o più aspetti non completati. Ciò avvisa sia gli utenti del codice che i programmatori di codice che una funzionalità o un bug devono essere risolti in una successiva revisione della sezione di codice pertinente. Doxygen ha una funzione interessante in cui elencherà tutti i Todos insieme nella propria sezione nell'output generato. È possibile disattivarlo modificando Doxyfile e modificando la riga GENERATE_TODOLIST = YES in GENERATE_TODOLIST = NO.
Correlato al tag Todo è il tag Bug, che può essere utilizzato in modo specifico per contrassegnare la documentazione che descrive un bug del software. Allo stesso modo, Doxyfile ha una riga GENERATE_BUGLIST = YES che fa sì che tutti i Bug vengano elencati nella propria sezione; questo può essere disattivato con GENERATE_BUGLIST = NO.