„Jeżeli dokumentacja nie powstaje równocześnie z kodem to nie powstanie nigdy.”
- Programiści są leniwi
- Tworzenie dokumentacji nie jest tak zabawne jak kodowanie
- Celowe gmatwanie kodu
- Brak czasu na wykonanie dokumentacji
- Pisanie przydatnej dokumentacji nie jest proste
- Tworzenie i aktualizowanie dokumentacji jest kosztowne
- Czy tworzenie dokumentacji to strata czasu?
- Agile Manifesto (jedno z przykazań) Working software over Comprehensive documentation
- „Real programmers don't document their programs”
- Dobrze napisany kod nie potrzebuje dokumentacji
- Zła dokumentacja gorsza od jej braku
- Dokumentacja powinna powstawać wraz z kodem. Dokumnetowanie gotowego programu jest o wiele bardziej czasochłonne.
- Brak dokumnentacji jako błąd kompilacji, np. uniemożliwienie zatwierdzenia nieudokumentowanego kodu w repozytorium
- Miary pokrycia dokumentacją: LOComents/LOCode
- Analiza statyczna wykrywająca brak komentarzy dokumentujących (Resharper wykrywa braki)
- Wymuszanie dobrych praktyk może prowadzić do nienajlepszych wyników
- Wiele nowoczesnych IDE wspomaga tworzenie dokumentacji i pozwala na automatyczne jej generowanie
- Doxygen - przenośny, darmowy, wsparcie dla wielu języków
- dotNet
- Dokumentacja techniczna: generowanie dokumentacji z plików źródłowych lub kodu pośredniego.
- Odkrywanie architektury również z nieudokumentowanego kodu - pomocne w przypadku dużych projektów (diagramy przedstawiające hierarchie zależności między plikami i klasami)
- Strony WWW, manuale, dokumentacja użytkowa
- Analiza złożoności kodu i architektury
- W C# opisy klas i metod opisuje się w specjalnych komentarzach używając tagów XML
- Komentarze jednolinijkowe
/// <summary> /// This class performs an important function. /// </summary> public class MyClass{}
- Komentarze blokowe\\
/** <summary>text</summary> */ /** <summary>text</summary> */ /** * <summary>text</summary> */
- Kompilacja kodu w VS generuje plik XML, który może zostać następnie przetworzony w innych narzędziach
cms Projekt.cs /doc:dokumentacja.xml
- Opisy typów: klasy, interfejsy, delegaty
- Opisy części składowych: pola, zdarzenia, własności, metody
- Komentarze dokumentacji nie mogą się odnosić do przestrzeni nazw
- Wyjściowy XML o nazwie takiej jak assembly widziany automatycznie przez IntlliSense
<summary> opis </summary>
krótki opis typu lub innego elementu. Widoczny przezIntelliSensei w oknieObject Browser<remarks> opis </remarks>
bardziej szczegółowy opis, widoczny w oknieObject 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>
Opis argumentu metody<returns>Opis</returns>
Opis wartości zwracanej
/// <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>
Opis własności (dodatkowo, oprócz summary)<exception cref=„typ”>Opis</exception>
/// <exception cref="System.Exception">Thrown when...</exception> public void DoSomething() { }
<typeparam name=„name”>description</typeparam>
Opis parametru typu dla typów generycznych
/// <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>
Pozwala wyszczególnić modyfikator dostepu i nie tylko
cref(code reference), odniesienie do innych elementów kodu: typy, metody, własności. W wygenerowanej dokumentacji uzyskujemy hiperłącza.<see cref =„typ”/>
odsyłacz do typu widocznego w projekcie
* <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”/>
referencja do argumentu metody
/// <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”/>
odnośnik do parametru typu
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>
Opis przykładu<code>fragment kodu</code>
przykładowy kod umieszczany wewnątrz sekcji <example><c>kod</c>
określa fragment tekstu jako kod
<para>Tekst</para>akapit- znaki większości i mniejszości (cytowanie) za pomocą: <, >
- tagi HTML: <b></b>, <i></i>, itd.
- dowolne tagi zgodne z XML
<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() { } }
- Komentarze nie są umieszczane z kodzie pośrednim → nie są dostępne poprzez mechanizm refleksji
- Każdy odokomentowany element kodu jest w pliku XML jednoznacznie określony
- Plik XML zawiera płaską listę takich elementów
- N - namespace, T - type (klasa, interfejs, …), F - pole, P - własność , M - metoda, E - zdarzenie, ! - bład
- Nazwy typów rozwijane są do pełnej formy
- Kompilator jest w stanie określić poprawność użycia tagów: exception, include, param, permission, see, seealso, typeparam
// Przed: public bool StringIsValid( string validateMe ) { … } // Po wpisaniu 3x/ (///) /// <summary> /// /// </summary> /// <param name="validateMe"></param> /// <returns></returns> public bool StringIsValid( string validateMe ) { … }
- GhostDoc - rozrzeszenie VS wspomagające tworzenie komentarzy dokumentujących
- Analizuje nazwy typów, metod i zmiennych aby automatycznie uzupełniać treść komentarzy
- synchronizacja komentarzy
- sprawdzanie pisowni
- generowanie plików
.chm - szablony tworzenia komentarzy
- narzędzia konsolowe
- dodawanie dowolnej zawartości do wygenerowanej dokumentacji
- Sandcastle - projekt MS, tworzenie dokumentacji w stylu MSDN, analizuje kod pośredni, plik XML opcjonalnie. Projekt już nie rozwijany.
- Niezależna aplikacja GUI lub rozszerzenie do VS 2010, 2012, 2013 (integracja z systemem kontroli wersji)
- Źródło: assembly (ddl, exe), xml, plik solucji + zależności
- Rodzaje dokumentacji: Compiled HTML Help 1 (.chm), MS Help 2 (.HxS), MS Help Viewer (.mshc), Open XML (.docx), strona WWW
- Sygnalizacja błedów, np.: brak komentarzy dla fragmentów kodu
- API Reference Content + Conceptual Content (MAML)
- języki: C++, C, C#, Objective-C, Java, Python, PHP, Fortran, Pascal, D
- przetwarza tylko pliki źródłowe
- formaty wyjściowe: HTML, PDF, LaTeX, PostScript, RTF, XML, man
- platformy: Windows, Mac OS X, Unix/Linux
- licencja GPL, powstał w 1997r., jest na bieżąco aktualizowany
- aplikacja konsolowa + nakładka GUI
- Dokumentacja techniczna generowana na podstawie komentarzy w kodzie
- Dokumentacja: plików, przestrzeni nazw, pakietów, klas, struktur, unii, szablonów, zmiennych, funkcji, makr, itd.
- Komentarze w plikach nagłówkowych, źródłowych lub w osobnych plikach
- Odkrywanie architektury także dla nieudokumentowanego kodu (opcja EXTRACT_ALL=yes)
- indeksy, relacje między obiektami, diagramy klas i grafy wywołań
- Strony WWW, manuale, dokumentacja użytkowa
- Formatowanie
wiki, tagi HTML, XML, style, …
- Kompatybilny z JavaDoc (1.1), qdoc3 (częściowo), ECMA-334 (C#)
- Automatycznie tworzy dowiązania do udokumentowanych typów, przestrzeni nazw, plików, itd.
- Generuje diagramy klas i diagramy współpracy (collaboration)
- Może współpracować z narzędziem
dot(Graphviz) w celu tworzenia diagramów zależności (dependency graphs), grafów wywołań i innych diagramów - Automatyczne wiązanie elementów dokumentacji z fragmentami kodu
- doxygen – program generujący dokumentację na podstawie utworzonego wcześniej pliku konfiguracyjnego i przeglądanych plików (źródeł programów i nie tylko).
- doxywizard – graficzna aplikacja ułatwiająca tworzenie pliku konfiguracyjnego dla dokumentacji danego projektu.
- doxytag – program pomocniczy pozwalający integrować zewnętrzną dokumentację (do której doxygen nie ma bezpośredniego dostępu) z dokumentacją tworzoną przez doxygen.
- graphviz – oprogramowanie wykorzystywane do tworzenia diagramów (grafó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
- JAVADOC_AUTOBRIEF=yes
/** Brief description which ends at this dot. Details follow * here. */
- JAVADOC_AUTOBRIEF=no
//! Brief description. //! Detailed description //! starts here.
- Komentarze mogą być umieszczone przed deklaracją lub definicją, w dowolnym miejscu pliku lub w osobnym pliku
- Opis może być umieszczony w różnych miejscach - wynik jest scalany
- Komentarze umieszczane tuż za dokumentowanymi elementami
int var1; ///< Brief description after the member int var2; /**< Detailed description after the member */
- Komendy strukturalne (poprzedzone \ lub @), np.
\brief,\class,@param
- \class, \struct, \union, \enum
- \fn dokumentacja funkcji
- \def dokumentacja dyrektywy
#define - \return dokumentacja wartości zwracanej przez funkcję
- \var dokumentacja zmiennej
- \namespace, \package, \file
- \see „zobacz także”, \ref - odnośnik
- \date dodaje sekcję daty
- Formatowanie tekstu zgodne z Markdown syntax
# This is a level 1 header ### This is level 3 header #######
- Linki
[Tekst linku](http://example.net/) <http://www.example.com> [Tekst](@ref MyClass)
- Obrazy
/*! - 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
- Tylko dla LaTeX i HTML
- Wymagania: latex, dvips, gs lub dla wersji HTML USE_MATHJAX
\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
- Sandcastle nie rozwijany juz , fork Sandcastle Help File Builder
- VSdocman API documentation for your C# and VB .NET code
- Ndoc - niestety, już nie rozwijany
- GhostDoc - rozszerzenie VS wspomagające tworzenie dokumentacji
- DoxyGen - przenośny, dasmowy, wsparcie dla wielu języków, aplikacja konsolowa ale jest wiele nakładek GUI