Dokumentation in C# - Sandcastle
Markus Fischer
http://groups.google.de/group/microsoft.public.de.german.entwickler.dotnet.csharp/browse_thread/thread/730b49a5f5adae1b/f84885e1ebd546e0?lnk=gst&q=sandcastle#f84885e1ebd546e0
gibt es zu Sandcastle eine gute deutsche Anleitung?
http://sandcastle.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=13873
Wei� jemand, ob das dann online/direkt geht? �nderung Code, �nderung Doku
oder umgekehrt?
Scheint ja kostenfrei zu sein oder gibt es jetzt bessere Alternativen?
Das was bei VS2008 dabei ist, ist nicht ausreichend.
Das logische Modell, die Architektur, Bilder l�sst sich nicht abbilden oder
ich wei� es nicht.
Viele Gr��e Markus
Immo Landwerth
> http://groups.google.de/group/microsoft.public.de.german.entwickler.dotnet.csharp/browse_thread/thread/730b49a5f5adae1b/f84885e1ebd546e0?lnk=gst&q=sandcastle#f84885e1ebd546e0
>
> gibt es zu Sandcastle eine gute deutsche Anleitung?
Mir ist keine bekannt. Was m�chtest Du denn wissen? Ein gute Einf�hrung
in MAML gibt es hier:
[Sandcastle MAML Guide 1.1.0.0]
http://www.codeplex.com/SandcastleStyles/Release/ProjectReleases.aspx?ReleaseId=17333
...allerdings auf englisch.
Wenn Du mit Sandcastle arbeiten willst, empfehle ich generell auch
Sandcastle Help File Builder (SHFB). Damit kann man in wenigen Minuten
was zusammenklicken.
[Sandcastle Help File Builder]
http://shfb.codeplex.com
> http://sandcastle.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=13873
>
> Wei� jemand, ob das dann online/direkt geht? �nderung Code, �nderung
> Doku oder umgekehrt?
Die Fragen habe ich jetzt nicht verstanden. Was meinst Du mit online/direkt?
> Scheint ja kostenfrei zu sein oder gibt es jetzt bessere Alternativen?
Sandcastle hat seine T�cken und Macken, aber mir ist nichts besseres
bekannt. Haupt Feature ist IMHO, dass man nicht nur reine Class Library
Doku erstellen kann, sondern auch allgemeine Themen mit Paragraphen,
Listen, Tabellen etc. Alles wird zusammengelinkt und man erh�lt eine
Doku mit einem einheitlichen Look & Feel. Ferne wird diese konzeptuelle
Doku auch in XML erstellt und ist (wenn man es richtig anstellt) frei
von Formatierungen und enth�lt daher nur noch semantischen Markup.
> Das was bei VS2008 dabei ist, ist nicht ausreichend.
Was ist bei VS2008 dabei? Du meinst doch nicht etwa das
Dokumentationstool von VS2002?
> Das logische Modell, die Architektur, Bilder l�sst sich nicht abbilden
> oder ich wei� es nicht.
Auch das habe ich wieder nicht verstanden. Redest Du vielleicht von den
Class Diagrams?
--
Immo Landwerth
Markus Fischer
>> http://sandcastle.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=13873
>>
>> Wei� jemand, ob das dann online/direkt geht? �nderung Code, �nderung
>> Doku oder umgekehrt?
umgekehrt.
>
> Die Fragen habe ich jetzt nicht verstanden. Was meinst Du mit
> online/direkt?
>
>> Scheint ja kostenfrei zu sein oder gibt es jetzt bessere Alternativen?
>
> Sandcastle hat seine T�cken und Macken, aber mir ist nichts besseres
> bekannt. Haupt Feature ist IMHO, dass man nicht nur reine Class Library
> Doku erstellen kann, sondern auch allgemeine Themen mit Paragraphen,
> Listen, Tabellen etc. Alles wird zusammengelinkt und man erh�lt eine Doku
> mit einem einheitlichen Look & Feel. Ferne wird diese konzeptuelle Doku
> auch in XML erstellt und ist (wenn man es richtig anstellt) frei von
> Formatierungen und enth�lt daher nur noch semantischen Markup.
>
>> Das was bei VS2008 dabei ist, ist nicht ausreichend.
>
> Was ist bei VS2008 dabei? Du meinst doch nicht etwa das Dokumentationstool
> von VS2002?
http://msdn.microsoft.com/de-de/library/2d6dt3kf(VS.80).aspx
wie macht man das richtig und was kommt dann f�r den Endkunden raus?
Gibt es irgendwo eine �bersicht, gute Anleitung.
http://msdn.microsoft.com/de-de/library/b2s063f7(VS.80).aspx
>
>> Das logische Modell, die Architektur, Bilder l�sst sich nicht abbilden
>> oder ich wei� es nicht.
>
> Auch das habe ich wieder nicht verstanden. Redest Du vielleicht von den
> Class Diagrams?
Da habe ich Probleme mit dem Overview, wenn ich mehrere Assemblies, Projekte
habe.
Die �bersicht kann nicht erstellt werden oder vermutlich wei� ich es halt
nicht.
Sch�nes WE
Markus
Immo Landwerth
>>> Wei� jemand, ob das dann online/direkt geht? �nderung Code, �nderung
>>> Doku oder umgekehrt?
>> Die Fragen habe ich jetzt nicht verstanden. Was meinst Du mit
>> online/direkt?
> ich meine ich �ndere den Quellcode, dann passt sich sofort die Doku an
> oder umgekehrt.
Achso. Nat�rlich musst Du die Doku neu erstellen, allerdings verwendet
SHFB ein MSBuild Projekt. Das hei�t, Du kannst (und solltest) die Doku
mit jedem neuen Build neu erstellen.
>>> Das was bei VS2008 dabei ist, ist nicht ausreichend.
>>
>> Was ist bei VS2008 dabei? Du meinst doch nicht etwa das
>> Dokumentationstool von VS2002?
> nein das
> http://msdn.microsoft.com/de-de/library/2d6dt3kf(VS.80).aspx
> wie macht man das richtig und was kommt dann f�r den Endkunden raus?
Achso *lach*, das ist nat�rlich nur um Klassenbibliotheken zu
dokumentieren. Du kannst mit SHFB die Doku zu Deiner Klassenbibliothek
entweder aus den ///-Kommentar generieren oder aber auch externe
Dokumentationsdateien schreiben.
Die ///-Kommentare haben den Vorteil, dass sie quasi automatisch in-sync
mit dem eigentlichen Code bleiben. Refactoring Werkzeuge wie R# �ndern
z.B. auch die Verweise (paramref, param, cref).
>>> Das logische Modell, die Architektur, Bilder l�sst sich nicht abbilden
>>> oder ich wei� es nicht.
>>
>> Auch das habe ich wieder nicht verstanden. Redest Du vielleicht von
>> den Class Diagrams?
> ja ich meine die Class Diagramms.
Es gibt einen Anbieter
[Drawbridge]
http://www.castleapps.com/
der es erlaubt in Sandcastle direkt Class Diagrams zu verlinken. So wie
ich das verstanden habe, generiert dieses Tool zum
Dokuerstellungszeitpunkt ein .png aus dem Klassendiagram und bettet es
automatisch in die resultierende Doku mit ein. Soweit ich wei�, erzeugt
es sogar eine HTML Image Map, sodass man tats�chlich nur auf die
einzelnen Shapes klicken muss um zum entprechenden API Referenztopic zu
gelangen. Ich habe allerdings selbst keine Erfahrung mit diesem Tool
gemacht.
> Da habe ich Probleme mit dem Overview, wenn ich mehrere Assemblies,
> Projekte habe.
> Die �bersicht kann nicht erstellt werden oder vermutlich wei� ich es
> halt nicht.
Ich habe dieses Problem in der Vergangenheit dadurch gel�st, dass ich
ein paar einleitende Topics erstellt habe (typischer Weise etwas in der
Art "Overview", "Getting Started", "Quick Start"). Wenn Du mal ein
Beispiel sehen m�chtest:
[NQuery Doku]
http://nquery.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=3466#DownloadId=21289
In Sandcastle werden diese Topics "Conceptual Content" genannt. Diese
werden auch mittels XML beschrieben, das XML Schema hei�t "Microsoft
Assistance Markup Language" (MAML). SHFB bietet eine rudiment�re
grafische Oberfl�che daf�r, allerdings muss letztlich das XML immer noch
von Hand geschrieben werden. Aber SHFB hilft, um mal einen Fu� in die
T�r zu bekommen :-)
--
Immo Landwerth