Dokumentation in C# - Sandcastle

[Markus Fischer]

Hallo,
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]

Post by 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?

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

Post by 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?

Die Fragen habe ich jetzt nicht verstanden. Was meinst Du mit online/direkt?

Post by Markus Fischer
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.

Post by Markus Fischer
Das was bei VS2008 dabei ist, ist nicht ausreichend.

Was ist bei VS2008 dabei? Du meinst doch nicht etwa das
Dokumentationstool von VS2002?

Post by Markus Fischer
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?

[Markus Fischer]

Hallo Immo,

Post by Immo Landwerth

Post by 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?

ich meine ich ändere den Quellcode, dann passt sich sofort die Doku an oder
umgekehrt.

Post by Immo Landwerth
Die Fragen habe ich jetzt nicht verstanden. Was meinst Du mit
online/direkt?

Post by Markus Fischer
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.

Post by Markus Fischer
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?
Gibt es irgendwo eine Übersicht, gute Anleitung.
http://msdn.microsoft.com/de-de/library/b2s063f7(VS.80).aspx

Post by Immo Landwerth

Post by Markus Fischer
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.
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]

Post by Markus Fischer

Post by Immo Landwerth

Post by Markus Fischer
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.

Post by Markus Fischer

Post by Immo Landwerth

Post by Markus Fischer
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).

Post by Markus Fischer

Post by Immo Landwerth

Post by Markus Fischer
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.

Post by Markus Fischer
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 :-)