Tvorba technické dokumentace aplikací v .NET

28. února 2003

•

Zkompilováním funkční aplikace útrapy vývojáře zdaleka nekončí. Abyste mohli plně využít výhod objektového přístupu k vývoji aplikací, nemůžete si dovolit zanedbat často opomíjenou stranu téže mince, tvorbu technické dokumentace. V tomto článku vám předvedu, jak si ji můžete maximálně usnadnit bez dalších nákladů na vývoj aplikace či komponent. Zaměřím se přitom na jazyky C# a Visual Basic.NET (bez závislosti na vývojovém prostředí Visual Studio.NET).

Příchod platformy .NET zbořil nejednu dosavadní programátorskou hradbu. Znovupoužitelnost a rozšiřitelnost kódu nabyla nových rozměrů s rozmetáním vzájemných rozdílů mezi jednotlivými jazyky bez nutnosti složitého COM dorozumívání (COM – Component Object Model, standard navržený společností Microsoft pro sdílení komponent v nativní podobě). Například VB programátor má již k dispozici nástroje k rozšíření funkčnosti komponent původně v C# (čti C sharp) a naopak. Aby ale tímto způsobem mohl opravdu fyzicky konat, musí funkcím dané komponenty (aplikace) dokonale porozumět bez nutnosti studia zdrojových kódů. Jedním z cílů technické dokumentace je právě toto odtajnění a podrobné vysvětlení vstupů a výstupů používané či rozšiřované komponenty.

Hlavní stavební kámen

Pro ukázku tvorby technické dokumentace si vymyslíme například třídu clCalculator:

‚<remarks>
‚Trida clCaltulator slouzi pro zakladni matematicke vypocty
‚</remarks>
‚<summary>Zakladni vypocetni operace</summary>
Public Class clCalculator
‚<summary>Mozne vypocetni akce</summary>
Public Enum enActions
   ‚<summary>Nasobeni</summary>
   multi
   ‚<summary>Scitani</summary>
   plus
   ‚<summary>Deleni</summary>
   divi
End Enum
‚<summary>promena A</summary>
Private iA As Int16
‚<summary>promena B</summary>
Private iB As Int16
‚<summary>vysledek operace</summary>
Private iResult As Int16
Public Sub New(ByVal a As Int16, ByVal b As Int16)
   iA = a
   iB = b
   iResult = Nothing
End Sub
‚<summary>Clen A</summary>
‚<value>Hodnota clenu A</value>
Public Property numberA() As Int16
   Get
    Return iA
   End Get
   Set(ByVal Value As Int16)
    If Not IsNothing(Value) Then
      iA = Value
    End If
   End Set
End Property
‚<summary>Clen B</summary>
‚<value>Hodnota clenu B</value>
Public Property numberB() As Int16
   Get
    Return iB
   End Get
   Set(ByVal Value As Int16)
    If Not IsNothing(Value) Then
      iB = Value
    End If
   End Set
End Property
‚<summary>Vraci vysledek vypocetnich operaci</summary>
‚<value>vysledek vypoctu</value>
Public ReadOnly Property getResult() As Int16
   Get
    Return iResult
   End Get
End Property
Public Sub Compute(ByVal operator As enActions)
   If IsNothing(iA) Or IsNothing(iB) Then
    Throw New Exception(„Invalid numbers“)
   Else
    Select Case operator
      Case enActions.divi
       iResult = iA \ iB
      Case enActions.multi
       iResult = iA * iB
      Case enActions.plus
       iResult = iA + iB
    End Select
   End If
End Sub
End Class

Ukázka je kódována v jazyce Visual Basic, ale vzhledem k jednoduchosti této třídy věřím, že bude srozumitelná také pro znalce C#.

Povšimněte si prosím XML značek, které jsem uvedl v poznámkách (‚) jednotlivých metod a vlastností. Tato vlastnost, Microsoftem nazývaná XML Documentation, umožňuje vývojářům komentovat zdrojový kód také pomocí sady sémantických XML značek. Výsledkem je posléze strukturovaný XML dokument, který detailně popisuje kompilované třídy. Proces generování tohoto XML dokumentu je možné spustit z prostředí Visual Studia.NET nebo také pomocí řádkového kompilátoru (csc.exe /doc:…), a tak máte zcela volnou ruku při volbě vývojového prostředí. Tuto vlastnost implementoval Microsoft zatím pouze pro jazyk C#, ale naštěstí i pro vývojáře ve Visual Basic existuje řešení.

C# vývojáři pouze nahradí označení poznámky za /// a mohou přeskočit následující kapitolu, která popisuje „vydolování“ XML dokumentu ze zdrojových kódů VB.

Nahrazení funkce „XML documentation“

Jak jsem zmínil již dříve, při použití jazyka Visual Basic budeme hledat nativní podporu „XML Documentation“ marně. Tento nedostatek nahradíme použitím open-source aplikace VB.DOC, jejímž cílem je výše uvedenou funkci zcela nahradit. Výsledek použití této aplikace odpovídá výsledku C# kompilátoru.

Jelikož se VB.DOC stále vyvíjí, můžete nalézt občas menší chybky. Na druhou stranu, některé z nedostatků, které jsem při testování verze 0.23 objevil, autor opravil již v následující verzi 0.24 (například podpora globálních výčtových typů – enum nebo podpora procedur s ByRef předáváním parametrů).

Aplikaci pouze určíte zkompilovanou komponentu (assembly), kořenový jmenný prostor a zdrojový kód dané komponenty. Vše ostatní již obstará sama. Samotné jádro aplikace je možné spouštět ve třech režimech:

aplikace příkazového řádku
aplikace s grafickým rozhraním
doplněk pro Visual Studio.NET

Malé upozornění pro potenciální uživatele – při tvorbě XML dokumentu si dejte pozor na zařazování tříd do jmenných prostorů. Například pokud máte u svého projektu nastaven implicitní kořenový jmenný prostor (root namespace), je ho potřeba zadat také při samotném generování. V opačném případě nedojde postup popsaný níže k očekávaným výsledkům. Ti čtenáři, kteří by si podobnou aplikaci raději napsali sami, mohou začít přečtením článku XML Documentation Tool, který se zabývá podobným tématem.

Generování technické dokumentace

Základem pro generování technické dokumentace bude XML dokument, popisující ukázkový zdrojový kód. K samotnému vytvoření bude použita aplikace NDoc, která dokáže přetransformovat připravený XML dokument hned do několika formátů:

formát známý ze stránek dokumentace .NET platformy na MSDN
JavaDoc
LaTeX
obecný XML formát připravený pro obecnější použití

Aby aplikace mohla vytvořit MSDN formát, budete ještě potřebovat MS HTML Help Workshop, který výsledné webové stránky zkompiluje do jednoho *.CHM souboru nápovědy Windows.

Aplikace NDoc nabízí opravdu pestrou škálu nastavitelných parametrů, které ovlivňují výsledný převod (například doplnění popisu u standardních objektových členů – constructor/destructor, syntaxe zápisu také pro jazyk VB, možnosti doplnění verze popisované „assembly“ a také přidává řadu nových sémantických značek oproti původnímu návrhu společnosti Microsoft).

Připravil jsem pro vás také ukázku výsledné transformace:

ve formátu *.CHM (Widows Help) (Pozor, některé z odkazů mohou vést na soubor nápovědy pro .NET Framework.)
bez kompilace do CHM – v podobě sady webových stránek (Pozor, některé z odkazů mohou vést na soubor nápovědy pro .NET Framework.)

Možné alternativy

Čtenáři, kteří pracují s Visual Studiem .NET, se jistě setkali s funkcí Build Comment Web Pages..., která může zde popisovaný způsob nahradit. Na rozdíl od aplikace NDoc však nenabízí standardní formáty a její použití s jazykem VB je omezené. Profesionálové také mohou sáhnout po aplikaci MS Visio (součást Architect distribuce Visual Studia.NET), ale toto řešení je vzhledem ke své ceně také poněkud méně dostupné.