Poznámka: články jsou již mnoho let staré, doba se posunula, mnoho věcí v nich doporučovaných je již dnes překonané - berte s rezervou!


Sandcastle – generování dokumentace z XML komentářů (nástupce NDoc)

Jak vědí asi všichni, kdo si trošku šáhli na .NET, svoji dokumentaci k třídám, metodám a atributům můžete vkládat přímo do kódu. Teď nemyslím klasické řádkové a blokové komentáře, ale XML komentáře pro jednotlivé prvky jazyka. Podrobnější popis metody najdete třeba v článku Tomáše Petříčka – C# – dokumentace pomocí XML komentářů. Já jen ukážu, jak to může vypadat v praxi:

V komentářových značkách (uvozených sekvencí ///) je napsaná dokumentace ke konstruktoru MyClass. S psaním těchto značek vám pomůže Visual Studio – stačí napsat onu uvozovací sekvenci před nějakou třídou (metodou, …) a VS vám vygeneruje kostru komentáře.

Dokumentační komentáře a intellisense

Proč psát takovéto dokumentační komentáře?

  • kód a dokumentace je na jednom místě, lze je snadno měnit obojí najednou (a je menší pravděpodobnost, že na to zapomenete)
  • vývojová prostředí zobrazují text dokumentačních komentářů v nápovědových bublinách – jak vidíte na obrázku, toto nesmírně usnadňuje psaní kódu.
  • Pokud pečlivě používáte dokumentační komentáře, ulehčíte práci sobě a především všem, kteří budou jednou používat váš kód.

To, že je ale dokumentace zapsaná přímo v kódu, má ale i nevýhodu – případný čtenář dokumentace musí procházet přímo zdrojáky, nebo si třeba nějak zobrazovat obsah assembly. Proto je dobré ještě komentáře vzít a dát je do samostatné dokumentace.

Vzpomínám si, že ve Visual Studiu 2003 tato možnost byla přímo zabudovaná, ve Visual Studiu 2005 již ne. Prý proto, že opensource projekt NDoc dělal to samé a lépe. Jenže ouha – vývoj NDoc skončil a nedá se použít pro .NET verze > 1.1. Prý bude NDoc možná zase oživen, ale to je teď irelevantní.

Microsoft totiž zareagoval na úpěnlivá volání programátorů a uvolnil vlastní nástroj – pod názvem Sandcastle ve verzi CTP pro volné použití. Sandcastle vám umožní vygenerovat dokumentaci do .chm souboru (HTML stránky spojené do jednoho souboru, ve stromové struktuře s indexem) nebo do webové stránky. Získáte tak dokumentaci velmi podobnou té z MSDN, všechno pěkně pohromadě (btw, web msdn má nový vzhled, všimli jste si?).

Sandcastle sám o sobě je konzolový nástroj, můžete si ale stáhnout také GUI nástroj Sandcastle Help File Builder, který už vám umožní pracovat s velmi slušným komfortem v grafickém prostředí, které je téměř identické s NDocem.

Sandcastle Help File Builder

V SHFB si jednoduše vložíte ty assembly, které chcete zahrnout do vaší dokumentace, nastavíte parametry dokumentace a spustíte proces (Build). Teď si řádnou chvíli počkáte (generování trvá i pro malé projekty třeba několik minut).

Už jsem si s SHFP trošku hrál, takže pár tipů:

  • po kliknutí na tlačítko Namespaces můžete doplnit komentáře k namespacům (které budou top-level uzly v hierarchii budoucí dokumentace)
  • propertou AdditionalContent můžete určit další HTML stránky, které chcete do výsledné dokumentace zahrnout – tedy třeba nějaké informace, které jste nechtěli psát do dokumentačních komentářů přímo do kódu
  • může se stát, že operace Build selže kvůli tomu, že chybí třeba nějaká assembly, která je standardní součástí .NET frameworku. Tyto assembly můžete doplnit do kolekce Dependecies (v Project Properties).
  • propertou HelpFileFormat můžete určit, zda chcete výstup v .chm souboru nebo jako webovou stránku
  • propertou Presentation Style můžete nastavit vzhled výsledného dokumentu
  • nastavením property DocumentInheritedFrameworkMembers zakážete dokumentování atributů a metod, které vaše třídy zdědily ze standardních typů .NETu (pokud ji necháte defaultně na true, budou např. všechny vaše objekty mít v dokumentaci metody Equals, GetHashCode, GetType a ToString), zvlášť pokud píšete komentáře v češtině, může to působit rušivě.
  • nastavením property DocumentInheritedMembers na false zakážete dokumentování všech zděděných atributů a metod (ne jen těch stadardních).

Sandcastle spolu se Sandcastle Help File Builderem je hodně dobře použitelný nástroj (i když zatím CTP) a doporučuji ho. Podle Sandcastle blogu byl použit i pro generování VS Orcas. S generováním dokumentace pro několik projektů jsem nenarazil na žádné problémy.

Odkazy:

Ohodnoťte prosím užitečnost článku




38
 
11
 
9
 
20
 
2
 
 
Vložit komentář:
 

 



 

 

Nepoužívejte žádné html ani texy značky, odřádkování se zachová. Pokud uvádíte zdrojový kód, můžete ho vložit mezi značky
<syntax jazyk="PHP">...</syntax>,
bude potom zformátován. Jako atribut můžete uvést PHP, C#, HTML, CSS a mnoho dalších.


opiste cislo Opište číslo:

 

18. 6. 2007 1:53:29
[1] (Martin Suchan (n3croman(at)gmail.com))
June CTP odpovědět
Snad by se ještě hodilo doplnit že během pondělka 18.6. vyjde nová June CTP verze, která nahradí současnou březnovou CTP.

Dále, NDoc existoval i ve verzi pro .NET 2.0, ale poslední verze je už více, než rok stará, viz: http://jonas.lagerblad.com/blog/ (web autora poněkud nefunguje, poslední verzi NDoc mám, pro případné zájemce, staženou)

Jinak, Sandcastle již používám delší dobu a je to velmi šikovná věcička, která ušetři čas. Určitě doporučuji minimálně vyzkoušet!
1. 3. 2008 13:34:45
[2] (Petr Láslo (laslo.petr(at)seznam.cz))
Můžeš poradit? odpovědět
Ahoj, můžeš se mi prosím ozvat na ICQ 491-577-497. Potřaboval bych s někým kdo ovládá .NET se poradit. Díky
10. 10. 2010 15:05:57
[3] (Tomas (vobrazek(at)atlas.cz))
Sandcastle Help File Builder odpovědět
Prosím o radu v Sandcastle Help File Builder 1.9.1.0. Do Documentations Sources jsem vložil projektovou část .csproj a .xml. Následně jsem zkusil kompilovat a vyskočila mi chyba -
SHFB: Error BE0033: No APIs found to document. See error topic in help file for details.
Nevím si rady co s chybou dělat. Zkoušel jsem různé možnosti a kombinace a stále se mi nepodařilo dostat výsledek.
Případně mi pošlete prosím aspoň funkční projekt .shfbproj, ať se mohu aspoň inspirovat.
Děkuji a omlouvám se za komplikace