View page as slide show

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

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 przez IntelliSense i w oknie Object Browser
  • <remarks> opis </remarks>
    bardziej szczegółowy opis, widoczny w oknie 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>
    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ą: &lt, &gt
  • 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.
  • Fork Sandcastle Help File Builder (SHFB)
  • 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
  • Lista wszystkich komend

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 
     ![Caption text](/path/to/img.jpg)

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