[C#] XML Documentatie

[marcusk]

De C# compiler kan dus een XML bestand genereren met de documentatie voor je klassen, maar wat moet je vervolgens doen met die documentatie? Ik zou verwachten dat er wel tooltjes zouden zijn die het omzetten naar HTML of een ander leesbaar formaat, want aan de XML alleen heb je niet zo veel IMO, maar die heb ik niet kunnen vinden. Mis ik soms iets ofzo?

[edit]
De gegenereerde XML vind ik ook nogal vaag:

code:

<doc>
  <members>
    <member name="T:namespace.klasse.methode">
     ...
    </member>
    etc...

Het zou veel handiger zijn als de namespace/klasse/methode structuur ook met XML zou zijn gerepresenteerd; op deze manier kun je niet bv. met XPath alle methoden van een klasse selecteren

[Verwijderd]

Zitten er niet een paar mooie .XSL bestanden bij Dan kan je naar elk willekeurig formaat transformeren .

Hier moet vast wel iets te vinden zijn op internet/google

[Verwijderd]

In Visual Studio.net: Tools / Build comment web pages

et voila

[marcusk]

Je zou idd verwachten dat er xsl bestanden bij zouden zitten, maar das dus niet het geval. Met google en av heb ik het ook niet kunnen vinden.

[marcusk]

Op donderdag 21 maart 2002 14:52 schreef Otis het volgende:
In Visual Studio.net: Tools / Build comment web pages

et voila

Hmmm, die heb ik dus niet.

[Verwijderd]

Op donderdag 21 maart 2002 14:54 schreef marcusk het volgende:

[..]

Hmmm, die heb ik dus niet.

Tja, dan zul je wat programmering moeten doen. Je kunt de XML file middels een XSLT naar HTML converteren, maar je zult de type informatie via reflection moeten terughalen. Dit is wel te doen, maar lastig.

[marcusk]

Op donderdag 21 maart 2002 14:58 schreef Otis het volgende:
Tja, dan zul je wat programmering moeten doen. Je kunt de XML file middels een XSLT naar HTML converteren, maar je zult de type informatie via reflection moeten terughalen. Dit is wel te doen, maar lastig.

Dat was ook een beetje mijn bedoeling als er nog geen tools voor waren

[Verwijderd]

Op donderdag 21 maart 2002 14:52 schreef marcusk het volgende:
Je zou idd verwachten dat er xsl bestanden bij zouden zitten, maar das dus niet het geval. Met google en av heb ik het ook niet kunnen vinden.

http://www.mantrotech.com/technology/csharp/article_using_xml_for_csharp_1.asp

google saves the day

[Scare360]

Op donderdag 21 maart 2002 14:52 schreef Otis het volgende:
In Visual Studio.net: Tools / Build comment web pages

et voila

Uhm staat er bij mij niet in ... custom tool manager blah... welke moet ik hebben, want die build comment web dinges heb ik dus default niet

[Verwijderd]

Op donderdag 21 maart 2002 22:33 schreef paulgielens het volgende:

[..]

Uhm staat er bij mij niet in ... custom tool manager blah... welke moet ik hebben, want die build comment web dinges heb ik dus default niet

Vaag. Bij mij staat hij onder de 'Add in manager' menu entry. (Visual Studio Enterprise Architect edition). Zit je wel in een C# project? In een C++ project zie ik hem nl. niet. Alleen C# heeft die tags en die docs generatie feature.

[marcusk]

zow: SharpDoc.zip. Das versie 0.1

Zo werkt ie:

1. De opgegeven assembly file (exe of dll) wordt geopend en d.m.v. reflectie worden alle typen en bijbehorende velden geladen.
2. De opgegeven xmldoc file wordt geladen en de documentatie daarin wordt aan de typen en velden toegevoegd.
3. Er wordt een xml-document gegenereerd (zie bv. Data.xml)
4. De XML-boom wordt d.m.v. XSL getransformeerd naar HTML.

En deze zijn ermee gegenereerd:

Documentatie van zichzelf

GoldParser Documentatie (die heeft ook een interface en enums)

(zijn alleen als voorbeeld; heb nog nauwelijks documentatie geschreven)

[mbravenboer]

Yummie, Yummie, Yummie!

Hulde! .

* mbravenboer zal er naar kijken (en wellicht gebruiken) als hij zich weer gaat bezighouden met het C# deel van het al vaker genoemde RMI-SOAP .

[marcusk]

Op maandag 25 maart 2002 19:59 schreef mbravenboer het volgende:
Yummie, Yummie, Yummie!

Hulde! .

tnx

[Verwijderd]

Op maandag 25 maart 2002 17:28 schreef marcusk het volgende:
zow: SharpDoc.zip. Das versie 0.1

Ziet er beter uit dan de door VS.net gegenereerde poop! Keep up the good work!

[marcusk]

Op maandag 25 maart 2002 20:16 schreef Otis het volgende:
Ziet er beter uit dan de door VS.net gegenereerde poop! Keep up the good work!

Ook tnx

Dit design heb ik gejat van de SDK Docs, maar dat had je vast al gezien

[stylee]

Mooie marcusk, errug handig.

[tomato]

Tsja, erg cool gedaan, maar dat was al gezegd geloof ik

[stylee]

Zie toevallig net een stukje over XML doc in C# voor proffesionals (helaas een klote vertaling als het inhoudelijk niet zo goed was had ik hem gelijk teruggebracht), ff quoten:

Om de XML-documentatie te genereren als het project gecompileerd wordt, geeft u een XML Documentation File op in het menu Build onder Configuration Properties op de eigenschappenpagina van het project.

Als het goed is moet je nu wel die Build->Build Comment Web Page het wel doen.

ps. niet getest

[Verwijderd]

Is dit alleen C# afhankelijk of is dit ook mogelijk voor andere .net talen (vb.net bv)?

En hoe herkent hij je comments bij functies en klasses eigenlijk? Is er een bepaald standaard (javadoc?) formaat hoe je je code moet becommentarieren?

[Verwijderd]

Op dinsdag 26 maart 2002 10:38 schreef KoekenBoes het volgende:
Is dit alleen C# afhankelijk of is dit ook mogelijk voor andere .net talen (vb.net bv)?

En hoe herkent hij je comments bij functies en klasses eigenlijk? Is er een bepaald standaard (javadoc?) formaat hoe je je code moet becommentarieren?

Zover ik weet hebben alleen C# en VB.NET het.
De comments worden door de compiler eruit gevist en in een XML document gezet. De wijze waarop het commentaar geschreven dient te worden staat ergens in de help files van de SDK (kan het zo snel niet vinden)

Niet uit de SDK maar hier staat wat info over de syntax

[marcusk]

Op dinsdag 26 maart 2002 10:43 schreef CoDeR het volgende:
Zover ik weet hebben alleen C# en VB.NET het.

Volgens mij alleen C# hoor.

[Verwijderd]

kon al geen voorbeeldje voor vb.net vinden. Vind ik wel erg raar trouwens dat dit alleen voor C# geimplementeerd is..

[marcusk]

Op dinsdag 26 maart 2002 12:49 schreef KoekenBoes het volgende:
kon al geen voorbeeldje voor vb.net vinden. Vind ik wel erg raar trouwens dat dit alleen voor C# geimplementeerd is..

idd. zo moeilijk kan het niet zijn om het ook aan de vb.net compiler toe te voegen lijkt me.

[Verwijderd]

Op dinsdag 26 maart 2002 12:49 schreef KoekenBoes het volgende:
kon al geen voorbeeldje voor vb.net vinden. Vind ik wel erg raar trouwens dat dit alleen voor C# geimplementeerd is..

De editors zelf zijn overgelaten aan de verschillende talenteams. Vandaar dat de C# editor wel #region kent en bv de C++ editor niet, of bv dat de C# editor outlining outhoudt per file en de C++ editor niet.

[Orphix]

* Orphix trekt z'n zwarte band aan en trapt het topic 4 maanden omhoog
Die sharpdoc kan ik dus niet meer downloaden
marcusk, als je hem nog hebt kan je het ergens weer online zetten?

Maar nu heb ik zitten zoeken op internet of er intussen al meer documentatie generators zijn, maar die kan ik niet vinden

Die standaard bij Visual Studio .NET vind ik dus 3x niks, het laat zelfs de private members zien en niet alfabetisch bijvoorbeeld.

Dus heeft iemand ervaring met een generator die goed werkt?
(en ook beetje customizable is e.d.)

[.oisyn]

Op donderdag 21 maart 2002 23:55 schreef Otis het volgende:

[..]

Vaag. Bij mij staat hij onder de 'Add in manager' menu entry. (Visual Studio Enterprise Architect edition). Zit je wel in een C# project? In een C++ project zie ik hem nl. niet. Alleen C# heeft die tags en die docs generatie feature.

niet? raar, ik zie m bij C++ projectjes wel (en hij werkt prima)

.edit: oh ik zie nu pas dat het een oud topic is. Niet dat dat voor mijn opmerking verder nog uitmaakt

[marcusk]

Op zondag 21 juli 2002 23:55 schreef Orphix het volgende:
* Orphix trekt z'n zwarte band aan en trapt het topic 4 maanden omhoog
Die sharpdoc kan ik dus niet meer downloaden
marcusk, als je hem nog hebt kan je het ergens weer online zetten?

Ohja, ik had geen ruimte meer op die @home dinges dus heb ik het bestand verwijderd
Ik heb em nu opnieuw geupload ergens anders: [url="http://www.gamecom.nl/files/SharpDoc2.zip"]SharpDoc2.zip[/url] (versie 0.2).

Maar nu heb ik zitten zoeken op internet of er intussen al meer documentatie generators zijn, maar die kan ik niet vinden

Toen ik net versie 0.2 gemaakt had vond ik ineens dit: [url="http://ndoc.sourceforge.net/"]nDoc[/url]. Ik heb em niet eens geprobeerd, maar aangezien daar 5 mensen aan werken zal het wel iets beter zijn dan mijn tooltje Vandaar dat ik zelf niet verder gegaan ben.

[Orphix]

Op maandag 22 juli 2002 01:01 schreef marcusk het volgende:

[..]

Ohja, ik had geen ruimte meer op die @home dinges dus heb ik het bestand verwijderd
Ik heb em nu opnieuw geupload ergens anders: [url="http://www.gamecom.nl/files/SharpDoc2.zip"]SharpDoc2.zip[/url] (versie 0.2).

Thank you

Toen ik net versie 0.2 gemaakt had vond ik ineens dit: [url="http://ndoc.sourceforge.net/"]nDoc[/url]. Ik heb em niet eens geprobeerd, maar aangezien daar 5 mensen aan werken zal het wel iets beter zijn dan mijn tooltje Vandaar dat ik zelf niet verder gegaan ben.

Deze werkt idd heel aardig. De opgeleverde documentatie ziet er vrijwel exact uit als de MSDN documentatie (Inclusief VB syntax ).