Tworzenie dokumentacji
„Jeżeli dokumentacja nie powstaje równocześnie z kodem to nie powstanie nigdy.”
Skąd się bierze nieudokumentowany kod?
- 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
Jak wymusić dobre praktyki
- 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
Narzędzia
- Wiele nowoczesnych IDE wspomaga tworzenie dokumentacji i pozwala na automatyczne jej generowanie
- Doxygen - przenośny, darmowy, wsparcie dla wielu języków
- dotNet
Zastosowanie
- 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
C# i komentarze z tagami XML
- 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
Tagi
<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
Referencje
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]; } }
Przykładowy kod
<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
Struktura i formatowanie tekstu
<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
Listy i tabele
<list type="bullet" | "number" | "table">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>
Dokumentacja w osobnym pliku
<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() { } }
Identyfikacja obiektów w pliku XML
- 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
Automatyczne uzupełnianie
// Przed: public bool StringIsValid( string validateMe ) { … } // Po wpisaniu 3x/ (///) /// <summary> /// /// </summary> /// <param name="validateMe"></param> /// <returns></returns> public bool StringIsValid( string validateMe ) { … }
GhostDoc
- GhostDoc - rozrzeszenie VS wspomagające tworzenie komentarzy dokumentujących
- Analizuje nazwy typów, metod i zmiennych aby automatycznie uzupełniać treść komentarzy
Dokumentacja pliku
Wersja Pro
- synchronizacja komentarzy
- sprawdzanie pisowni
- generowanie plików
.chm - szablony tworzenia komentarzy
- narzędzia konsolowe
- dodawanie dowolnej zawartości do wygenerowanej dokumentacji
Sandcastle
- 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)
SHFB GUI
Szablon projektu w VS
Konfiguracja
Doxygen
- 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
Zastosowanie
- 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, …
Inne cechy
- 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
Narzędzia
- 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)
Komentarze
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
|
Struktura
/**
* \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
Komendy strukturalne
- \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
Markdown syntax
- 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
Listy
/*! - Poziom 1 Tekst dla poziomu 1 - Poziom 2 + element 2.1 + element 2.1 - Poziom 3 * element 3.1 */
Tabele
nagłówek 1 | nagłówek 2 ---------- | ----------- komórka | komórka komórka | komórka
Tagi HTML
/*!
Lista
<ul>
<li> element listy
<ol>
<li> element list <br> dalszy ciąg
<li> element listy
</ol>
</ul>
*/
Grupowanie
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
Wzory matematyczne
- 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]
Narzędzie konsolowe
Generowanie pliku konfiguracji
doxygen -g [plik_konfiguracji]
Generowanie dokumentacji
doxygen plik_konfiguracji
Szablony stylów
HTML
doxygen -w html header.html footer.html stylesheet.css
LaTeX
doxygen -w latex header.tex doxygen.sty
RFT
doxygen -w rtf rtfstyle.cfg
Doxygen GUI
Tryb działania
Wyjście
Diagramy
Kolory HTML
Expert mode
Więcej informacji
- 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