Documentatie als MSDN genereren, maar dan handmatig

[NickThissen]

Hey,

Ik ben aan het werken aan het implementeren van een script engine (in VB.NET), dat wil zeggen dat ik functies moet aanmaken die de gebruiker mbv een scriptje (gewoon via een textbox) kan aanroepen. Dit houdt in: de naam van de functie bepalen, het aantal en type argumenten, een eventuele return type, en de implementatie.

Nu moet ik deze functies documenteren, zodat men later kan zien welke functies ik allemaal aangemaakt heb zonder mijn code te moeten doorspitten.

Ik ben al vaker tooltjes als SandCastle (of NDoc ofzoiets) tegengekomen die heel mooi en snel documentatie in een soort van MSDN stijl kan maken, door gewoon executables of DLLs en de XML comments te lezen. Zo kun je in VB.NET simpel XML comments boven je classes, functies etc zetten en zal SandCastle er een mooi help bestandje van maken waar je kan browsen door de verschillende namespaces, de classes in die namespaces, die functies in die classes, etc.

Nu zou het mooi zijn als ik zo'n zelfde soort documentatie kon maken. Het probleem echter is nu dat deze tooltjes op .NET code werken (wellicht ook met andere talen, dat is niet het punt), maar ik moet de documentatie van mijn functies in de script engine hebben (dus niet de documentatie van de source van de script engine zelf, enkel de functies die ik erin definieer). Voor zover ik weet kan SandCastle dit natuurlijk niet automatisch genereren (ik zou niet weten waar hij de informatie vanaf moet halen), maar ik hoop dat ik misschien handmatig de functies erin kan gooien, met een omschrijving en een lijstje van argumenten, en dat zo'n tooltje dan alsnog een mooie help file (of een aantal HTML bestanden van mijn part) aanmaakt.

Ik kan de script taal het beste omschrijven als enkel bestaande uit static functies. Elke functie heeft een 'Namespace' (hoewel 'static class' misschien een betere naam is) en een functie naam, en natuurlijk een lijstje met argumenten.

Een stom voorbeeldje kan zijn:

code:

int i
string s

i = 1
s = "Hello"

Log.WriteString(s)
Log.WriteInt(i)
Message.Show(i + 1)

De functies zijn hier:
- Log.WriteString, waarbij Log de 'namespace' (zoals ik al zei, static class is misschien beter) is en Write de functie naam,
- Log.WriteInt, Log is de namespace en WriteInt de functienaam.
- Message.Show, Message is de namespace en Show de functienaam.

Simpel genoeg lijkt me...

De documentatie die hieruit moet rollen zou dan zoiets zijn als:

[b]Namespaces:[/b]
- Log
- Message

Klikken op Log levert dan:

[b]Functions in namespace Log:[/b]
- WriteString(string message)
- WriteInt(int value)

Klikken op WriteInt levert dan

[b]Function Log.WriteInt[/b]

[u]Description[/u]: writes an integer value to the log.

[u]Arguments[/u]:
 - value: int.
   The integer value to write to the log.

of iets dergelijks...
In andere woorden: een soort van MSDN stijl help file of webpagina zelfs waar je makkelijk door de namespaces kan klikken om functies op te zoeken, dan de informatie over die functie op te zoeken, en zo steeds door te klikken.


Weet iemand of er tooltjes bestaan die dit mogelijk maken? Of werken deze tooltjes echt alleen met bestaande code zoals een .NET executable + XML comments, en is er geen manier om handmatig de functies, omschrijvingen, argumenten etc op te geven?

Ik snap dat ik alle informatie zelf moet gaan opgeven (dus een namespace maken met omschrijven, daarin functies gaan maken met omschrijving, etc), maar dat is geen probleem, er is geen manier om dit automatisch te laten doen.


Bedankt voor enige informatie


EDIT
Waar ik al aan gedacht had is om deze functies daadwerkelijk in een VB.NET/C# projectje aan te maken, gewoon losse functies zonder implementatie, met wat XML comments, en er daarna SandCastle op los te laten. Dat heb ik even snel geprobeerd, maar dat levert toch niet op wat ik wil. Het grootste probleem is dat onze naamgeving van namespace niet overeenkomt met de naamgeving in .NET (of elke andere taal denk ik), en dat de types die de script engine ondersteunen niet exact overeenkomen met de types in .NET. Ook geeft SandCastle veel te veel informatie, dingen als chain of inheritance enzo heb ik allemaal helemaal niet nodig. Heel simpel functie naam + omschrijving + lijstje argumenten (elk argument met omschrijving) is meer dan voldoende.

Als er niets gevonden wordt dan kan ik altijd zelf nog een tooltje schrijven wat een simpel documentje aanmaakt ofzo (een heel help bestand met doorlinken etc zal teveel tijd gaan kosten), maar als er al zoiets bestaat wil ik natuurlijk niet alles opnieuw gaan uitvinden.

[ Voor 15% gewijzigd door NickThissen op 06-12-2010 21:41 ]

[DoDo]

edit:

nvm, fout gelezen

[ Voor 87% gewijzigd door DoDo op 06-12-2010 22:05 ]

[Haan]

Sandcastle gebruik je icm met de Sandcastle Help File Builder deze spuugt netjes een help file (.chm) of HTML pagina's uit.

[Matis]

Wij gebruiken op de zaak Doxygen voor het genereren van (inhouse) documentatie.

Voor VB.net zijn er een aantal zogenaamde helper files te vinden. Op die pagina staan ook Visual Studio specifieke filters en helper files.

Dit schijnt een van de betere VB.net filters te zijn voor Doxygen. Al heb ik verder geen ervaring met Doxygen voor VB.net. Wel voor C++, C# en Java

Zoals je hier kunt zien poept Doxygen een hele hoop verschillende formaten uit. MAN-pages, RTF, XML, HTML, Word-formaten en zelfs Latex.

Als het jou om HTML-pagina's te doen is, raad ik je aan deze pagina eens te lezen met de mogelijkheden.

[ Voor 87% gewijzigd door Matis op 06-12-2010 22:34 ]

[NickThissen]

Voor zover ik zo snel kan zien zijn al deze tools gemaakt om source files te lezen en daarmee automatisch documentatie aan te maken. Maar dat is dus niet wat ik moet hebben, aangezien er geen source files zijn. Ook het feit dat ik VB.NET gebruik is compleet irrelevant. Het gaat om de functies die ik in de script engine definieer. Dat definieren doe ik dmv VB.NET code, maar het gaat om de functies zelf, hoe de eindgebruiker deze functies in zijn script kan gebruiken.

Ik zal dus handmatig de functies moeten toevoegen, met hun beschrijving en argumenten.

De enige reden waarom ik het vergelijk met tools als SandCastle en, voor zover ik zo snel kan zien, Doxygen, is omdat de output wat die tools genereren heel handig is, en het zou mooi zijn als ik zo'n zelfde output kon krijgen, maar dan handmatig (dus niet dmv het lezen van source files).

[gorgi_19]

NickThissen schreef op maandag 06 december 2010 @ 23:08:
Voor zover ik zo snel kan zien zijn al deze tools gemaakt om source files te lezen en daarmee automatisch documentatie aan te maken. Maar dat is dus niet wat ik moet hebben, aangezien er geen source files zijn.

Volgens mij leest hij juist de gegenereerde XML-files uit die gegenereerd worden. Die moet je zelf kunnen genereren / wegschrijven.

[Haan]

gorgi_19 schreef op dinsdag 07 december 2010 @ 07:06:
[...]

Volgens mij leest hij juist de gegenereerde XML-files uit die gegenereerd worden. Die moet je zelf kunnen genereren / wegschrijven.

Klopt, je moet in je project settings wel even aanzetten dat die XML wordt gegenereerd tijdens het builden van het project. Die XML voer je vervolgens aan de tool die documentatie gaat genereren.

Maar als ik de TS zo nog eens lees is dat niet wat er wordt bedoeld. Dat is gewoon een beschrijving van de tool, ik zie niet in hoe je dat zou kunnen genereren, het komt een beetje neer op Reflector pakken en de exe/dll van het tooltje daarin openen.

[gorgi_19]

Haan schreef op dinsdag 07 december 2010 @ 07:37:
Maar als ik de TS zo nog eens lees is dat niet wat er wordt bedoeld. Dat is gewoon een beschrijving van de tool, ik zie niet in hoe je dat zou kunnen genereren, het komt een beetje neer op Reflector pakken en de exe/dll van het tooltje daarin openen.

Als je zelf de XML 'schrijft', vul je daar zelf de functies in en kan je nog steeds tools als sandcastle gebruiken

[Haan]

Dat is inderdaad een mogelijkheid

[NickThissen]

Als ik zelf de XML file schrijf moet ik nog steeds een source hebben die daarmee overeenkomt, en die heb ik simpelweg niet.

Ik ben nu nogmaals aan het proberen om deze source gewoon aan te maken, noem het maar 'simuleren', er zit totaal geen implementatie in natuurlijk, het zijn gewoon losse functies met commentaar die overeenkomen met de functies die ik in de script taal definieer.

Ik heb nu deze C# code gebruikt:

C#:

namespace DocTest
{
   /// <summary>
   /// Contains the data types used in the scripting language.
   /// </summary>
    public static class DataTypes
    {
        /// <summary>
        /// Represents a string of characters.
        /// </summary>
        public class String {}

        /// <summary>
        /// Represents an integer number.
        /// </summary>
        public class Integer {}

        /// <summary>
        /// Represents a true/false value.
        /// </summary>
        public class Boolean { }

        /// <summary>
        /// Represents a real number.
        /// </summary>
        public class Double { }

        /// <summary>
        /// Represents a date (and time?).
        /// </summary>
        public class Date { }

        /// <summary>
        /// Represents no type, used for fuctions without return values.
        /// </summary>
        public class Void { }
    }
}

C#:

namespace DocTest
{
    /// <summary>
    /// Contains functions related to logging.
    /// </summary>
    public static class Log
    {
        /// <summary>
        /// Writes a String message to the log file.
        /// </summary>
        /// <param name="message">The message to write.</param>
        /// <returns>Void</returns>
        public static DataTypes.Void WriteString(DataTypes.String message)
        {
            return null;
        }

        /// <summary>
        /// Writes an Integer value to the log file.
        /// </summary>
        /// <param name="value">The value to write.</param>
        /// <returns>Void</returns>
        public static DataTypes.Void WriteInt(DataTypes.Integer value)
        {
            return null;
        }
    }

    /// <summary>
    /// Contains functions related to messages and dialogs.
    /// </summary>
    public static class Message
    {
        /// <summary>
        /// Displays a message to the user.
        /// </summary>
        /// <param name="message">The message to display.</param>
        /// <returns>Void</returns>
        public static DataTypes.Void Show(DataTypes.String message)
        {
            return null;
        }

        /// <summary>
        /// Asks for user input via a dialog.
        /// </summary>
        /// <param name="prompt">The text shown in the dialog.</param>
        /// <returns>The input of the user.</returns>
        public static DataTypes.String GetInput(DataTypes.String prompt)
        {
            return null;
        }
    }
}

Als ik dit nu compileer en met SandCastle de help file genereer dan kom ik in ieder geval in de buurt, maar het is nog niet wat ik wil.

Ik heb de output even geupload zodat jullie kunnen meekijken mocht je dat willen:
www.nickthissen.nl/Files/Documentation.chm

Wat ik liever niet zie:

• De Namespace (DocTest) van het project mag eigenlijk helemaal weg
• De verschillende DataTypes staan allemaal rechtstreeks in de Classes van de namespace, in plaats van netjes onder een kopje DataTypes. Dit is misschien op te lossen door DataTypes een enum te maken, maar an kan ik mijn functies geen DataTypes.String laten terug geven of iets dergelijks, dus dat werkt ook niet. De verschillende datatypes classes zitten genest in de DataTypes static class dus ik had gehoopt dat de help file ook netjes die hierarchie zou weergeven.
• Als je op Log klikt bijvoorbeeld, dan kom je in de 'Log Class' pagina. Ik heb liever dat dit 'Log Namespace' heet, maar ik denk niet dat ik daar veel aan kan doen. Ik kan er mee leven als het class genoemd wordt.
• In elke pagina van classes of functies staat de Syntax in C#, VB en C++. Dat moet gewoon weg. De syntax van onze script taal is natuurlijk anders, dus ik wil de syntax van onze scripttaal zien en niet van C# etc...
• Inheritance hierarchy: weg ermee graag.
• See also: mag in principe blijven, maar alleen 'Log Members' is interessant, en zou misschien wat duidelijker op de pagina moeten staan in plaats van helemaal onderaan geplakt.
• De Log Members pagina is vrij goed, daar kan ik mee leven.
• Doorklikken naar een functie (bijv WriteString) krijg je weer de syntax in drie talen die ik niet moet hebben. Het lijstje met parameters is dan wel weer goed.

Dat is eigenlijk min of meer wat ik hoop te bereiken...

Wat zijn m'n opties? Is dit mogelijk met tools als SandCastle? Ik heb even door de project properties gelopen maar kon zelfs niet vinden om dingen als Inheritance Hierarchy uit te zetten, laat staan zelf een eigen Syntax voorbeeld op te geven (zou ook niet weten waar ik dat zou moeten doen).

Bedankt.

[NickThissen]

Als dit niet mogelijk is (en het lijkt erop van niet als niemand hier een tooltje kent) dan zal ik zelf aan de slag gaan om iets in elkaar te draaien.

Wellicht dat jullie wat tips hebben om de output te genereren? Ik kan wel een tooltje schrijven waarin ik de namespaces en functies kan declareren, en dat tooltje kan dit dan naar XML wegschrijven ofzo.
Het liefste heb ik een soort van webpagina (gewoon offline) waarin men kan doorlinken, maar om dit automatisch te genereren vanuit een XML file gaat nog wat tijd in zitten lijkt me...