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

JavaDoc

Doxygen - przenośny, darmowy, wsparcie dla wielu języków

dotNet

Sandcastle , Sandcastle Help File Builder

VSdocman API documentation for your C# and VB .NET code

Ndoc - niestety, nie rozwijany od 2005

GhostDoc - rozszerzenie VS wspomagające tworzenie komentarzy do dokumentacji

Document! X

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

XML Documentation Comments MSDN

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

Doxygen Intergration in Visual Studio 2010 Environment on junweblog

Quick C# Documentation using XML

XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files by J. Andrew Schafer