Doksizás

Mindenki utál doksit írni, nem kicsit, nagyon. A legtöbb, amire egy fejlesztőt rá lehet venni, az némi (nem több) XML komment írása a C# forráskódba, azt is csak azért, mert az IntelliSense megjeleníti. Sokszor találjuk magunkat olyan projektben, ahol a megrendelő forráskód szinten szeretné újrafelhasználni a munkánk eredményét, amihez legjobban egy MSDN-szerű CHM formátumú dokumentációt tudna használni.

Korábban erre a célra az NDocot használtuk, van vele azonban néhány probléma. A legfontosabb, hogy a projekt elaludt és bár teljesen nyílt forráskódú és sokan használják, senki nem veszi a fáradtságot, hogy érdemben besegítsen. Ez azért probléma, mert az utolsó változat még nem támogatja tökéletesen a .NET 2.0-át és azon belül leginkább a generikus típusokat, hanem hibával elszáll. Van belőle egy trükközött 1.3.1 verzió, ami legalább továbbmegy, de az sem tökéletes. Ráadásul nálam éppen Windows Beasta alatt valami single threaded apartment hibával elhal a konzolos változat, így nem tudjuk automatikusan beépíteni a fordítási folyamatba.

Hogy mit használ a Microsoft azt sokáig homály fedte, egy idő óta azonban elérhető a Sandcastle project előzetes változata, három napja a júniusi CTP. Szerintem aki ezt először meglátja mind azt mondja, hogy milyen szép egyszerű dizájn, de a fene se akarja használni. Pedig ezzel, pontosabban még a márciusi CTP-vel készült az Orcas béta dokumentációja is. Ami rém gusztustalanná teszi az egészet az az, hogy lényegében XSLT transzformációk sorozataként áll elő minden tartalom. Ugyan kapunk néhány XSLT fájlt a letöltéskor, de ha valamit módosítani akarunk (pl. copyright vagy preliminary szöveg), akkor az XML-be kell belemászni. A megfelelőbe. 

Ráadásul nem egy transzformációt kell végeznünk, hanem például CHM fájl előállításához egy egész sorozatot. Nálam például az alábbi szkript build.cmd prototype DLLnevekiterjesztésnélkül módon indítva CHM kimenetet ad, ha telepítve van a HTML Help Workshop, abban van ugyanis a HTML Help Compiler (hhc.exe):

    @echo off
    @echo - PATH modositasa...
    set DXROOT=C:Program FilesSandCastle
    set PATH=c:WINDOWSMicrosoft.NETFrameworkv2.0.50727;%DXROOT%ProductionTools;C:Program FilesHTML Help Workshop;C:Program FilesMicrosoft Help 2.0 SDK;%PATH%

    rem Alapertelmezes szerint comments.xml fajlt keres a Sandcastle, modositani kell a configban *.xml-re!
    @echo - Bemeneti fajlok masolasa
    copy ..bindebug*.dll . /Y >nul
    copy ..bindebug*.xml . /Y >nul

    @echo - Output mappa torlese...
    if exist Output rmdir Output /s /q  >nul

    @echo - MRefBuilder futtatasa...
    MRefBuilder %2.dll /out:reflection.org >nul

    @echo - Az eredmeny atalakitasa...
    XslTransform /xsl:"%DXROOT%ProductionTransformsApplyPrototypeDocModel.xsl" reflection.org /xsl:"%DXROOT%ProductionTransformsAddGuidFilenames.xsl" /out:reflection.xml  >nul

    @echo - Topic manifest keszitese...
    XslTransform /xsl:"%DXROOT%ProductionTransformsReflectionToManifest.xsl"  reflection.xml /out:manifest.xml  >nul

    @echo - Kimeneti mappastruktura letrehozasa...
    call "%DXROOT%Presentation%1copyOutput.bat"  >nul

    @echo - BuildAssembler futtatasa (ez nagyon sokaig tart, turelem)...
    BuildAssembler /config:"%DXROOT%Presentation%1configurationsandcastle.config" manifest.xml  >nul

    @echo - HTML Help project fajl letrehozasa...
    XslTransform /xsl:"%DXROOT%ProductionTransformsReflectionToChmProject.xsl" reflection.xml /out:Output%2.hhp /arg:project=%2  >nul

    @echo - TOC generalasa...
    XslTransform /xsl:"%DXROOT%ProductionTransformscreatePrototypetoc.xsl" reflection.xml /out:toc.xml  >nul

    @echo - HTML Help project informacio letrehozasa...
    XslTransform /xsl:"%DXROOT%ProductionTransformsTocToChmContents.xsl" toc.xml /out:Output%2.hhc  >nul
    XslTransform /xsl:"%DXROOT%ProductionTransformsReflectionToChmIndex.xsl" reflection.xml /out:Output%2.hhk  >nul

    @echo - CHM eloallitasa...
    hhc Output%2.hhp  >nul

    @echo - CHM fajl masolasa
    copy Output%2.chm . >nul

    @echo - Atmeneti fajlok torlese...
    del manifest.xml  >nul
    del reflection.org  >nul
    del reflection.xml  >nul
    del toc.xml  >nul
    del *.dll  >nul
    del *.xml  >nul
    rmdir IntelliSense /s /q
    rmdir Output /s /q

    @echo Kesz.

Ha valakinek nem tetszik a prototype stílusú kimenetet, választhat vs2005 és már vsorcas közül is. Ez utóbbi neve ne tévesszen meg senkit, nem azzal fog készülni a Visual Studio 2008 dokumentációja.

Van ugyan néhány GUI, de ennek a projektnek az ereje mégis abban rejlik, hogy be tudjuk építeni a fordítási folyamatunkba. Ha így teszünk, akkor készüljünk fel rá, hogy nagyon lassú, sok nagyságreddel lassabb az NDocnál, legalábbis az én gépemen. A GUI-k közül a fantáziadús SandcastleGUI nevű projekt előnye, hogy grafikus felületen megmondhatjuk, hogy mit hogyan szeretnénk lefordítani és az így létrejött egyedi formátumú projekt fájlt GUI nélkül, parancssori környezetben is tudjuk használni, így ez végülis automatizálható.

Akinek ezzel sikerült kedvet csinálni, a következő címeken talál bővebb információkat:

Más mit használ?

 

Technorati tags: , ,

Vélemény, hozzászólás?

Adatok megadása vagy bejelentkezés valamelyik ikonnal:

WordPress.com Logo

Hozzászólhat a WordPress.com felhasználói fiók használatával. Kilépés / Módosítás )

Twitter kép

Hozzászólhat a Twitter felhasználói fiók használatával. Kilépés / Módosítás )

Facebook kép

Hozzászólhat a Facebook felhasználói fiók használatával. Kilépés / Módosítás )

Google+ kép

Hozzászólhat a Google+ felhasználói fiók használatával. Kilépés / Módosítás )

Kapcsolódás: %s