Automatische Dokumentation

[snowy]

Hallo,

In C#.NET gibt es ja die Möglichkeit mittels XML-Tags eine XML Doku erstellen zu lassen. So weit kein Problem.

Wie bekomme ich dann eine schöne Word/PDF Doku da raus?

Durch googeln bin ich auf NDOC gestoßen. Bei der Installtion wird aber .NET FRAMEWORK 1 gefordert. Ich nutze 3.5 SP1 deshalb habe ich dann abgebrochen.

Was habe ich jetzt für Möglichkeiten...?

Vielen Dank!

[Bernhard Geyer]

Doc-O-Matic kann sowas.

[Myst]

Microsoft selbst bietet dafür Sandcastle an.

Ich persönlich bevorzuge DocProject, was auf Sandcastle aufbaut.

Mfg Myst

[snowy]

Danke für die Tipps.

Doc-O-Matic habe ich mir die Gratisversion runtergeladen. Habe das Programm gestartet und die *.cs Dateien angegeben.

Aber wo kann ich jetzt den Build starten? Was für eine Datei wird dann erzeugt?


@DocProject:
Ich habe wie in der anleitung:

http://docproject.codeplex.com/Wiki/...ringTitle=Home

ein Source Projekt angelegt und die Klasse mit den XML Tag kommentiert. Danach ein DocProject angelegt. dort bin ich mit dem Verweis beim Assistenten auf das source Projekt niocht klar gekommen. Da kann man im nachhinein über Verweis hinzufügen angeben.
Jetzt kommt aber die Meldung das keine Projekt Quellen zur Dokumentierung gefunden wurden..

Unter Verweise ist das Quell-Projekt eingetragen.

[Ralf Jansen]

Ich kenne Doc-O-Matic im speziellen jetzt nicht aber bist du dir sicher das du da Sourcecode dateien angeben mußt?
Eigentlich benutzen diese Tools(zumindest die die ich kenne) die bei einem Build erzeugten XML Dateien, wenn man denn dem Compiler in den Projektoptionen gesagt hat das er auch XML Dateien mit der Doku neben dem eigentlichen Compilat erzeugen soll.

[gfoidl]

Hallo,

ich verwende den Sandcastle-Helpfile-Builder (oder wie der genau heißt). Ist einfach zu bedienen (Projekt angeben, ein paar Einstellungen zur "Kosmetik", Doku erzeugen). Einziger Nachteil ist dass Sandcastel etwas langsam ist.

Downloadlink mit Google ermittelbar.

mfG Gü

[snowy]

Ich habe jetzt mit DocProject die generierte XML Datei geladen und damit ein set von HTML Dateien gebaut. Damit wiederum über einen Converter HTML-2-CHM ("Abee CHM Maker") ein CHM File (Help 2.x) gebaut.

DocProject hat auch eine Einstellung Help 2.x da kommt eine Fehlermeldung das dies nicht erzeugt werden konnte obwohl ich das SDK 2008 installiert habe. Wo der Compiler enthalten ist.

Aber über meinen Umweg mit dem Converter geht es auch.

Danke an alle!

[gfoidl]

chm-Dateien sind doch HTML-Help 1.x - oder?

HTML-Help 2.x wäre *.hxs (oder so ähnlich).

mfG Gü

[snowy]

Ja hast recht.Ich hatte mich geiirt.

es wird gleich ein chm File erzeugt. Bei help 2 Format macht er Probleme.

Das chm File ist aber das ws ich möchte.

[gfoidl]

Zur Info: Für CHM gibt es von Mircosoft auf den HTML Help Compiler.

mfG Gü

[snowy]

Danke für den Tipp.

Eine Frage noch:

Meine Applikation deren Code ich dokumentieren will, ist eine Solution, bestehend aus 2 Projekten. Eins ist in C# geschrieben und das andere in VB.NET.

Wenn ich in der VB Klasse mein XML Tag setzen will

/// <summary>
/// Foo
/// </summary>

Kommt ein Syntaxfehler...

[gfoidl]

In VB.net werden Kommentare mit ' eingeleitet.

Für die XML-Dok. sollte '' oder ''' gehen.

mfG Gü

PS: Das ' ist das Zeichen bei Shift + #

[Myst]

Guten Abend.

Kurze Aufklärung noch zu DocProject:
Du hast die Möglichkeit 2 verschiedene Projekte anzulegen:

• DocProject
  DocSite Web Applicaton

Bei ersterem stehen dir nur HTML Help 1.x und 2.x zur Verfügung. Bei letzterem wird dir zusätzlich noch eine ganze Webanwendung gebastelt (verhält sich ähnlich wie die MSDN - sieht recht schmuck aus)

Wenn du das Projekt erstellst, klickst du dich am besten einfach durch, ohne größere Einstellungen vorzunehmen - die wirst du später sowieso tiefgehender bearbeiten müssen.

Hast du das jeweilige Projekt angelegt. findest du entsprechend detailierte Eigenschaften, wenn du im Projektmappenexplorer (oder anderweitig) auf dein DocProject - Projekt rechtsklickst und im Kontextmenü "DocProject Properties" auswählst. Unter anderem findest du dort die Buildeigenschaften, wo du unter dem Punkt "External sources" deine Assembly und die zugehörige XML-Datei mit den Metadaten angeben solltest. Beachte, dass dein Projekt nicht in die Visual Studio Solution eingebunden werden muss.

Natürlich kannst du die Einstellungen auch direkt im XML bearbeiten bzw. die Quelldaten von DocProject bearbeiten. Es sei dir frei gestellt.

Für weitere Informationen bezüglich verfügbaren SDK's bzw. dir fehlenden Compilern siehe hier: MSDN

Mfg Myst

PS: Wie gfoidl bereits sagte:

Einziger Nachteil ist dass Sandcastel etwas langsam ist.

DocProject baut wie gesagt ebenfalls auf Sandcastle auf und ist daher entsprechend "langsam" (noch langsamer). Du solltest also einen Kaffee für größere Assemblys einplanen.

[snowy]

Danke nochmal für die zusätzlichen Hinweise.

Ich verwende in meinem Programm Schnittstellenklassen zu *.dll's. Dafür sind schon Dokus vorhanden. Wie kann ich diese Klassen kennzeichnen, das dafür keine Dokumentation gefodert bzw. angelegt wird? (Damit die Warnungen nicht mehr angezeigt werden, aufgrund fehlender XML-Tags).

Mit welchem Tag kann ich für eine Enumeration die Member kommentieren?

[Ralf Jansen]

Warnungen für fehlende Doku schaltet man mit

#pragma warning disable 1591

aus.

Enum Member werden wie jeder andere Teil auch mit dem Summary Tag kommentiert.

        /// <summary>
        /// MyDocumentation
        /// </summary>
        public enum myValue
        {
            /// <summary>
            /// MyDocumentation
            /// </summary>
            None,
            /// <summary>
            /// MyDocumentation
            /// </summary>
            SomeOtherValue,
        }

Um dir bei der Kommentierung helfen zu lassen, insbesondere was die Generierung der nötigen Tags betrifft, solltest du dir mal GhostDoc ansehen.