~~SLIDESHOW~~ ====== 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 * [[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html|JavaDoc]] * [[http://www.stack.nl/~dimitri/doxygen/|Doxygen]] - przenośny, darmowy, wsparcie dla wielu języków * dotNet * [[https://sandcastle.codeplex.com|Sandcastle ]], [[https://github.com/EWSoftware/SHFB|Sandcastle Help File Builder]] * [[http://www.helixoft.com/vsdocman/overview.html|VSdocman]] API documentation for your C# and VB .NET code * [[http://ndoc.sourceforge.net/|Ndoc]] - niestety, nie rozwijany od 2005 * [[http://submain.com/products/ghostdoc.aspx|GhostDoc]] - rozszerzenie VS wspomagające tworzenie komentarzy do dokumentacji * [[http://www.innovasys.com/product/dx/overview|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\\ /// /// This class performs an important function. /// public class MyClass{} * Komentarze blokowe\\ /** text */ /** text */ /** * text */ ===== ===== * 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 ===== * '' opis '' \\ krótki opis typu lub innego elementu. Widoczny przez ''IntelliSense'' i w oknie ''Object Browser'' * '' opis '' \\ bardziej szczegółowy opis, widoczny w oknie ''Object Browser'' \\ /// /// You may have some primary information about this class. /// /// /// You may have some additional information about this class. /// public class TestClass { /// text for Main static void Main() { } } ===== ===== * ''Opis'' \\ Opis argumentu metody * ''Opis'' \\ Opis wartości zwracanej \\ /// Określa status. /// Określa kontekst. /// Zwraca zero. public static int DoWork(int Int1, float Float1) { return 0; } ===== ===== * ''Opis'' \\ Opis własności (dodatkowo, oprócz summary) * ''Opis'' \\ /// Thrown when... public void DoSomething() { } ===== ===== * ''description'' \\ Opis parametru typu dla typów generycznych \\ /// /// Creates a new array of arbitrary type /// /// The element type of the array public static T[] mkArray(int n) { return new T[n]; } * ''Opis'' \\ 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. * '''' \\ odsyłacz do typu widocznego w projekcie \\ * \\ /// DoWork is a method in the TestClass class. /// Here's how you could make a second paragraph in a description. /// for information /// about output statements. /// /// public static void DoWork(int Int1) { } ===== ===== * '''' \\ referencja do argumentu metody \\ /// DoWork is a method in the TestClass class. /// The parameter takes a number. /// public static void DoWork(int Int1) { } ===== ===== * '''' \\ odnośnik do parametru typu \\ public class TestClass { /// /// Creates a new array of arbitrary type /// /// The element type of the array public static T[] mkArray(int n) { return new T[n]; } } ===== Przykładowy kod ===== * ''Opis'' \\ Opis przykładu * ''%%fragment kodu%%'' \\ przykładowy kod umieszczany wewnątrz sekcji * ''kod'' \\ określa fragment tekstu jako kod ===== Struktura i formatowanie tekstu ===== * ''Tekst'' akapit * znaki większości i mniejszości (cytowanie) za pomocą: %%<%%, %%>%% * tagi HTML: , , itd. * dowolne tagi zgodne z XML ===== Listy i tabele ===== term description term description ===== Dokumentacja w osobnym pliku ===== '''' \\ pozwala pobrać opis z zewnętrznego pliku XML. Argumentami jest nazwa pliku, ścieżka do tagu XML, jego nazwa i identyfikator /// 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/ (///) /// /// /// /// /// 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 {{ http://community.submain.com/blogs/tutorials/7Initialcommentcreated_15BAC3D2.png?500 |}} ===== Dokumentacja pliku ===== {{ http://community.submain.com/blogs/tutorials/11FileHeader_7730374E.png |}} ===== 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 [[https://github.com/EWSoftware/SHFB|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) ===== ===== {{ http://ewsoftware.github.io/SandcastleTools/media/SandcastleLayers.jpg?700 |}} ===== SHFB GUI ===== {{ http://ewsoftware.github.io/SHFB/media/MainForm.png }} ===== Szablon projektu w VS ===== {{ http://ewsoftware.github.io/SHFB/media/VSNewProjectDlg.png }} ===== Konfiguracja ===== {{ http://ewsoftware.github.io/SHFB/media/VSProjectPropsEditor.png }} ===== Doxygen ===== {{ http://www.stack.nl/~dimitri/doxygen/images/doxygen.png|}} * 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) ===== ===== {{ zajecia:npr:doxygen_architektura.png?700 |}} ===== 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 * [[http://www.stack.nl/~dimitri/doxygen/manual/commands.html|Lista wszystkich komend]] ===== Markdown syntax ===== * Formatowanie tekstu zgodne z [[http://daringfireball.net/projects/markdown/|Markdown syntax]] \\ # This is a level 1 header ### This is level 3 header ####### * Linki \\ [Tekst linku](http://example.net/) [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
  • element listy
    1. element list
      dalszy ciąg
    2. element listy
*/
===== 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 ===== {{ http://www.stack.nl/~dimitri/doxygen/manual/form_4.png|}} * 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 ===== {{ zajecia:npr:doxygen_wizard_project.png?700 |}} ===== Tryb działania ===== {{ zajecia:npr:doxygen_wizard_mode.png?700 |}} ===== Wyjście ===== {{ zajecia:npr:doxygen_wizard_output.png?700 |}} ===== Diagramy ===== {{ zajecia:npr:doxygen_wizard_diagrams.png?700 |}} ===== Kolory HTML ===== {{ zajecia:npr:doxygen_html_color_tune.png?700 |}} ===== Expert mode ===== {{ zajecia:npr:doxygen_expert_project.png?700 |}} ===== Więcej informacji ===== * [[https://msdn.microsoft.com/en-us/library/b2s063f7.aspx|XML Documentation Comments]] MSDN * [[https://sandcastle.codeplex.com|Sandcastle ]] nie rozwijany juz , fork [[https://github.com/EWSoftware/SHFB|Sandcastle Help File Builder]] * [[http://www.helixoft.com/vsdocman/overview.html|VSdocman]] API documentation for your C# and VB .NET code * [[http://ndoc.sourceforge.net/|Ndoc]] - niestety, już nie rozwijany * [[http://submain.com/products/ghostdoc.aspx|GhostDoc]] - rozszerzenie VS wspomagające tworzenie dokumentacji * [[http://www.stack.nl/~dimitri/doxygen/|DoxyGen]] - przenośny, dasmowy, wsparcie dla wielu języków, aplikacja konsolowa ale jest wiele nakładek GUI * [[http://junweihuang.info/blog/?p=305|Doxygen Intergration in Visual Studio 2010 Environment]] on junweblog * [[http://www.codeproject.com/Articles/8061/Quick-C-Documentation-using-XML|Quick C# Documentation using XML]] * [[http://msdn.microsoft.com/en-us/magazine/cc302121.aspx|XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files]] by J. Andrew Schafer