Dokumentation mit Sandcastle

1
Dokumentation mitSandcastle

• 21.11.2006 Ralf Karle

EMail Ralf.Karle_at_t-online.de
2
Was ist Sandcastle ?

• Laut http//blogs.msdn.com/sandcastle/default.as
  px
• 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

• /// ltsummarygta stack of intslt/summarygt
• /// ltremarksgtfixed sizelt/remarksgt
• public class IntStack
• private int m_values null
• private int m_CurrentPos 0
• /// ltsummarygt
• /// Initializes a new instance of the
  ltsee cref"IntStack"/gt class.
• /// lt/summarygt
• /// ltparam name"size"gtThe size.lt/paramgt
• public IntStack(int size) ...
• /// ltsummarygt
• /// Gets a value indicating whether this
  ltsee cref"IntStack"/gt is empty.
• /// lt/summarygt
• /// ltvaluegtltcgttruelt/cgt if empty
  otherwise, ltcgtfalselt/cgt.lt/valuegt
• public bool Empty ...

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\ltProgram Filesgt\EWSoftware\Sandcastle Help
  File Builder\ SandcastleBuilderConsole.exe"
  docsamplePrototype.shfb

7
Links

• Sandcastle - November 2006 CTPhttp//www.microsof
  t.com/downloads/thankyou.aspx?familyIdE82EA71D-DA
  89-42EE-A715-696E3A4873B2displayLangen
• Microsoft HTML Help Workshophttp//msdn.microsoft
  .com/library/default.asp?url/library/en-us/htmlhe
  lp/html/hwMicrosoftHTMLHelpDownloads.asp
• Sandcastle Helpbuilder (GUI)http//www.codeplex
  .com/Wiki/View.aspx?ProjectNameSHFB
• Sandcastle MS Build scripthttp//codeplex.com/M
  SBuildSandcastle
• Sandcastle Blogshttps//blogs.msdn.com/sandcast
  le/
• Sandcastle Wikihttp//www.sandcastledocs.com
• Sandcastle Forumhttp//forums.microsoft.com/MSD
  N/ShowForum.aspx?ForumID66SiteID1

8
Links II

• XML Documentation in Chttp//msdn2.microsoft.com
  /en-us/library/b2s063f7.aspx
• XML Documentation in Visual Basichttp//msdn2.mic
  rosoft.com/en-us/library/ms172652.aspx