Dokumentation mit Sandcastle

1. Dokumentation mitSandcastle 21.11.2006 – Ralf Karle EMail:Ralf.Karle@t-online.de

2. Was ist Sandcastle ? Laut : http://blogs.msdn.com/sandcastle/default.aspx Mission Statement: • Enable managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel Sandcastle Overview: • Produces quality, comprehensive, familiar MSDN-like documentation. • Works with or without authored comments. • Supports Generics and .NET Framework 2.0 • Sandcastle has 2 main components (MrefBuilder and Build Assembler) • MrefBuilder generates reflection xml file for Build Assembler • Build Assembler includes syntax generation, transformation..etc • Sandcastle is used internally to build .Net Framework documentation

3. Installation Downloadadressen siehe Links • Installation der Sandcastle CTP • Installation des Microsoft HTML Help Workshop • Installation des Sandcastle Helpbuilder von Erics Woodruff

4. Vorbereitung des C#/VB Projekts • Code mit Kommentaren versehensiehe (http://msdn2.microsoft.com/en-us/library/b2s063f7.aspx) • In den Projekteinstellungen : XML Documentation aktivieren

5. Code - Beispiel /// <summary>a stack of ints</summary> /// <remarks>fixed size</remarks> public class IntStack { private int [] m_values = null; private int m_CurrentPos = 0; /// <summary> /// Initializes a new instance of the <see cref="IntStack"/> class. /// </summary> /// <param name="size">The size.</param> public IntStack(int size) [...] /// <summary> /// Gets a value indicating whether this <see cref="IntStack"/> is empty. /// </summary> /// <value><c>true</c> if empty; otherwise, <c>false</c>.</value> public bool Empty [...] /// <summary> /// Pushes the specified int value to the stack /// </summary> /// <param name="intValue">The int value.</param> public void Push( int intValue ) [...] /// <summary> /// Pops a value from stack. /// </summary> /// <returns>the top value</returns> public int Pop() [...] } XML Doc Ausgabe

6. Erstellen der Hilfe mit dem Sandcastle Helpbuilder Mit der GUI • Sandcastle Helpbuiler starten • New Project • Project speichern • Ggf. Assemblies editieren • Ggf. Namesspaces editieren • Weitere Attribute setzen • Build Project • fertig Commandline: "C:\<Program Files>\EWSoftware\Sandcastle Help File Builder\ SandcastleBuilderConsole.exe" docsample[Prototype].shfb

7. Links • Sandcastle - November 2006 CTPhttp://www.microsoft.com/downloads/thankyou.aspx?familyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displayLang=en • Microsoft HTML Help Workshophttp://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp • Sandcastle – Helpbuilder (GUI)http://www.codeplex.com/Wiki/View.aspx?ProjectName=SHFB • Sandcastle – MS Build scripthttp://codeplex.com/MSBuildSandcastle • Sandcastle – Blogshttps://blogs.msdn.com/sandcastle/ • Sandcastle – Wikihttp://www.sandcastledocs.com • Sandcastle – Forumhttp://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1

8. Links II • XML Documentation in C#http://msdn2.microsoft.com/en-us/library/b2s063f7.aspx • XML Documentation in Visual Basichttp://msdn2.microsoft.com/en-us/library/ms172652.aspx