„Jeżeli dokumentacja nie powstaje równocześnie z kodem to nie powstanie nigdy.”
/// <summary> /// This class performs an important function. /// </summary> public class MyClass{}
/** <summary>text</summary> */ /** <summary>text</summary> */ /** * <summary>text</summary> */
cms Projekt.cs /doc:dokumentacja.xml
<summary> opis </summary> IntelliSense i w oknie Object Browser<remarks> opis </remarks> Object Browser /// <summary> /// You may have some primary information about this class. /// </summary> /// <remarks> /// You may have some additional information about this class. /// </remarks> public class TestClass { /// text for Main static void Main() { } }
<param name='nazwa'>Opis</param> <returns>Opis</returns> /// <param name="Int1">Określa status.</param> /// <param name="Float1">Określa kontekst.</param> /// <returns>Zwraca zero.</returns> public static int DoWork(int Int1, float Float1) { return 0; }
<value>Opis</value> <exception cref=„typ”>Opis</exception> /// <exception cref="System.Exception">Thrown when...</exception> public void DoSomething() { }
<typeparam name=„name”>description</typeparam> /// <summary> /// Creates a new array of arbitrary type <typeparamref name="T"/> /// </summary> /// <typeparam name="T">The element type of the array</typeparam> public static T[] mkArray<T>(int n) { return new T[n]; }
<permission>Opis</permission> cref (code reference), odniesienie do innych elementów kodu: typy, metody, własności. W wygenerowanej dokumentacji uzyskujemy hiperłącza.<see cref =„typ”/> * <seealso cref ="typ"\>\\ /// <summary>DoWork is a method in the TestClass class. /// <para>Here's how you could make a second paragraph in a description. /// <see cref="System.Console.WriteLine(System.String)"/> for information /// about output statements.</para> /// <seealso cref="TestClass.Main"/> /// </summary> public static void DoWork(int Int1) { }
<paramref name=„nazwa”/> /// <summary>DoWork is a method in the TestClass class. /// The <paramref name="Int1"/> parameter takes a number. /// </summary> public static void DoWork(int Int1) { }
<typeparamref name=„nazwa”/> public class TestClass { /// <summary> /// Creates a new array of arbitrary type <typeparamref name="T"/> /// </summary> /// <typeparam name="T">The element type of the array</typeparam> public static T[] mkArray<T>(int n) { return new T[n]; } }
<example>Opis</example> <code>fragment kodu</code> <c>kod</c> <para>Tekst</para> akapit<list type="bullet" | "number" | "table">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>
<include file='filename' path='tagpath[@name=„id”]' />
pozwala pobrać opis z zewnętrznego pliku XML. Argumentami jest nazwa pliku, ścieżka do tagu XML, jego nazwa i identyfikator
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' /> class Test { static void Main() { } }
// Przed: public bool StringIsValid( string validateMe ) { … } // Po wpisaniu 3x/ (///) /// <summary> /// /// </summary> /// <param name="validateMe"></param> /// <returns></returns> public bool StringIsValid( string validateMe ) { … }
.chm
wiki, tagi HTML, XML, style, …dot (Graphviz) w celu tworzenia diagramów zależności (dependency graphs), grafów wywołań i innych diagramów
Dla języków wywodzących składnię od C: C/C++/C#/Objective-C/PHP/Java
| Styl JavaDoc | Styl QtDoc |
|---|---|
| Wielolinijkowe | |
/**
tekst
**/
| /*!
text
*/
|
| Jednolinijkowe | |
/// tekst
| //! tekst
|
/**
* \brief Krótki opis
*
* Szczegółowy opis
* dodatkowa linia
*
* @param Opis wejściowego parametru funkcji lub
metody
* @param ...
* @return Opis zwracanej wartości
*/
Doxygen jest bardzo elastyczny, wspiera różnorodne formy komentowania kodu
/** Brief description which ends at this dot. Details follow
* here.
*/
//! Brief description. //! Detailed description //! starts here.
int var1; ///< Brief description after the member int var2; /**< Detailed description after the member */
\brief, \class, @param#define# This is a level 1 header ### This is level 3 header #######
[Tekst linku](http://example.net/) <http://www.example.com> [Tekst](@ref MyClass)
/*! - Poziom 1 Tekst dla poziomu 1 - Poziom 2 + element 2.1 + element 2.1 - Poziom 3 * element 3.1 */
nagłówek 1 | nagłówek 2 ---------- | ----------- komórka | komórka komórka | komórka
/*!
Lista
<ul>
<li> element listy
<ol>
<li> element list <br> dalszy ciąg
<li> element listy
</ol>
</ul>
*/
Każda grupa będzie się znajdować na osobnej stronie. Elementami grupy mogą być pliki, klasy, przestrzenie nazw, zmienne, itd.
\defgroup label name
Dodawanie do grupy
\addtogoup label
Odnośnik do grupy
\ingroup label
Referencja
\ref label
\f[
|I_2|=\left| \int_{0}^T \psi(t)
\left\{
u(a,t)-
\int_{\gamma(t)}^a
\frac{d\theta}{k(\theta,t)}
\int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
\right\} dt
\right|
\f]
Generowanie pliku konfiguracji
doxygen -g [plik_konfiguracji]
Generowanie dokumentacji
doxygen plik_konfiguracji
HTML
doxygen -w html header.html footer.html stylesheet.css
LaTeX
doxygen -w latex header.tex doxygen.sty
RFT
doxygen -w rtf rtfstyle.cfg
