This document discusses how to build effective API documentation using tools like Visual Studio and Sandcastle Help File Builder. It provides guidance on writing clear XML documentation comments, creating conceptual and reference topics, including code samples, and generating help files in different formats. The document also demonstrates the workflow and configuration for a sample documentation project in Sandcastle.
2. Intel Information Technology
Intro
Agenda
How to build meaningful API documentation using
Microsoft Visual Studio (and extensions)
XML code comments
Microsoft Assistance Markup Language (MAML)
Sandcastle Help File Builder (SHFB)
Presentation
Slides
Links
Notes
2
5. Intel Information Technology
Role models (or not)
Founding fathers
“A well regulated militia being necessary to the security of a free state, the right
of the people to keep and bear arms shall not be infringed.”
Anonymous
Lather, rinse, repeat.
IKEA
5
6. Intel Information Technology
Culture
Richard Dawkins
“Some people find clarity threatening. They like muddle, confusion, obscurity.
So when somebody does no more than speak clearly it sounds threatening.”
6
7. Intel Information Technology
Documenting code*
Class
Start with a word like “Represents”
“Represents a Windows button control.”
Constructor
Start with a word like “Initializes”
“Initializes a new instance of the Button class.”
Method
General method: Start with a verb
“Conceals the control from the user.”
Method returning a boolean value: Start with “Returns whether”
“Returns whether the specified key is a regular input key or a special key
that requires preprocessing.”
7
8. Intel Information Technology
Documenting code (continued)*
Event
Start with a phrase such as “Raised when” or “Occurs when”
“Occurs when the user double-clicks the Button control.”
Property
General: Use a noun or start with verbs such as “Gets”, “Sets”, “Gets or sets”
“Gets or sets the height of the control.”
Boolean: Start with “Indicates whether”
“Indicates whether the control is visible.”
XML element
Use a noun-based phrase
“The city’s postal code.”
8
9. Intel Information Technology
Toolbox
Visual Studio Extensions
GhostDoc (free)
Automatically generates XML documentation comments for methods and
properties based on their type, parameters, name, and other contextual
information
Visual Studio Spell Checker (free)
Checks the spelling of comments, strings, and plain text as you type or
interactively with a tool window
Sandcastle Help File Builder
9
10. Intel Information Technology
Sandcastle Help File Builder (SHFB)
About
Creates help files for managed class libraries containing both conceptual and API
reference topics
Requires HTML Help Workshop (can be installed along with SHFB)
Download from CodePlex (free, open source)
Includes
Command-line tools
IDE (stand-alone)
Visual Studio integration (VS 2005 or later)
Documentation
"Sandcastle XML Comments Guide"
"Sandcastle MAML Guide"
10
11. Intel Information Technology
Microsoft Assistance Markup Language (MAML)
About
XML-based markup language
Used to generate help files
Defines contextual rules of the XML element structure
Gets transformed into “presentational” formats (chm, docx, etc)
Dynamic (generated by Visual Studio from XML comments) or static (authored
by hand)
11
12. Intel Information Technology
Help file options (SHFB)
Formats
HTML Help 1 (chm)
MS Help 2 (HxS), MS Help Viewer (mshc)
NOT RECOMMENDED
Open XML (docx)
Can be later exported into a PDF document
Website (HTML/ASP.NET)
Styles
VS2010, VS2013
Open XML document (conflicts with VS2010, VS2013)
12
13. Intel Information Technology
Workflow (simplified)
SANDCASTLE PROJECT
CLASS LIBRARY PROJECT
Build process (SHFB)
13
.NET
compiler
Assembly
XML doc
file
Source
code file
Topic file
Media file
Content
layout file
Token file
Sandcastle
compiler
Help doc
14. Intel Information Technology
SHFB process (class library solution)
Steps to build XML documentation file(s)
Set existing class library project’s compile/build configuration to generate XML
documentation
See MSDN article: How to: Generate XML Documentation for a Project
Can be set only for one build target (debug, release)
Define XML comments for public classes, methods, properties, etc
More on this later
14
15. Intel Information Technology
SHFB process (SHFB project)
Steps to build documentation
Add SFHB project to the solution and configure project properties
Add XML documentation file(s) to the SFHB project’s documentation sources
Add logo icon file and define the logoFile transform arg
Enable required build components
Exclude namespaces, classes, methods, properties, etc that you don’t want to
make public (implicitly or explicitly)
Enter summaries (namespaces, API reference root topic)
Define tokens (string substitutions) for reuse in the documentation
Include media (images, etc) files (if needed)
Define content layout (mark the API reference insertion point) and topic files
15
19. Intel Information Technology
Logo
About
Logo appears in the page headers
Supports common image format (.bmp, .gif, .jpg, .jpeg, .png)
Use .png (compressed, supports transparency)
How
Add image file to the Icons folder
Define appropriate settings in the Sandcastle project properties under the
Transform Args tab
logoFile, logoPlacement, etc
19
21. Intel Information Technology
Recommended build components
API Token Resolution
Resolves tokens in XML comments.
Code Block Component
Searches for <code> elements within reference XML comments and
conceptual content topics and colorizes the code within them. It can also
include code from an external file or a region within the file.
IntelliSense Component
Extracts XML comments into files that can be used for IntelliSense.
Syntax Component
Creates syntax sections in topics using the syntax filter languages selected in
the project. It can also group and sort code snippets based on the order of the
defined syntax generators.
21
23. Intel Information Technology
Add document sources to the SHFB project
Include documentation files
Include XML documentation files
The corresponding DLLs will be added automatically
– If not, include the DLLs, too
Or include project files
Sandcastle will determine XM/DLL files from the project settings
23
25. Intel Information Technology
Visibility settings
Define inclusion/exclusion rules
Reasonable defaults
All public members
Plus
– Attributes on types and their members
– Inherited base class members
Edit API filter
Customize visibility of particular members/namespaces
25
28. Intel Information Technology
Using tokens for string substitution
Can be used in
Project properties (summaries)
Topic files
XML comments (code)
Use a <token> element with the token ID
28
<introduction>
<para>This document describes the <token>PRODUCTNAME</token> API.</para>
</introduction>
30. Intel Information Technology
Media files
Add media files to project
Use the Media folder to store media files
Final images
Source files (Photoshop, Visio, etc)
– Set Build Action to “None”
Assign ID to each media file
Reference images from topic files (or comments)
Use the <mediaLink> element
Reference media file by its ID
30
<mediaLink>
<image placement="center" xlink:href="Architecture"/>
</mediaLink>
31. Intel Information Technology
Help file contents
Components of the good API documentation*
Overview
Explains what advantages developers have in using the platform, and in
some cases, provide an architectural description of the platform.
Getting started
Helps the developer get started, in the form of step-by-step tutorials or
simpler walkthroughs.
Sample code
Offers well-commented code samples that developers can build on.
Reference materials
Provide detailed information about each class, member, function or XML
element.
31
32. Intel Information Technology
Content layout
Content.layout file
Defines topic hierarchy
Every topic
Must be mapped to a topic (aml) file (under the Content folder)
Must have an ID (GUID or other)
May be associated with keywords
One (and only one) topic
May define the API documentation insertion point
BKMs
Have the physical file hierarchy resemble the topic hierarchy
Name topic (aml) files after the topic titles
32
35. Intel Information Technology
Topic file elements
About
Context-driven element structure
Documented in “Sandcastle MAML Guide” (installed with Sandcastle)
Examples
Block elements
<introduction>, <title>, <para>, <table> (<tableHeader>, <row>, <entry>), <list>
(<listItem>), <code>
Link elements
<link>, <externalLink>, <codeEntityReference>
Media elements
<mediaLink>, <mediaLinkInline>
Miscellaneous elements
<token>
35
39. Intel Information Technology
Code samples (inline)
Use the <code> element with inline code
Put code inside of the CDATA section
39
/// <example>
/// <code language="C#">
/// <![CDATA[
/// // User extension will hold user info.
/// UserExtension user = new UserExtension();
///
/// // Name will hold the user's name parts.
/// Name name = new Name();
///
/// // Name parts can be in UTF-8.
/// name.FamilyName = "Bouchärd";
/// name.GivenName = "René";
/// name.MiddleName = "H";
///
/// // Save name in the user extension object.
/// user.Name = name;
/// ]]>
/// </code>
/// </example>
40. Intel Information Technology
Code samples (snippets)
Define commonly used code snippets in a .snippets file
Each snippet is identified by
Unique ID (format: ExampleId#SampleId)
Language (supported: VisualBasic, CSharp, ManagedCPlusPlus, JSharp, and
JScript)
40
Use the <codeReference> element to reference code snippet
Can combine snippets
<codeReference>CreateInstance#Local,Static</codeReference>
<?xml version="1.0" encoding="utf-8"?>
<examples>
<item id=“CreateInstance#Local">
<sampleCode language=“CSharp">MyClass obj = new MyClass();</sampleCode>
<sampleCode language=“VisualBasic">Dim obj As MyClass = New MyClass()</sampleCode>
</item>
<item id=“CreateInstance#Static">
<sampleCode language=“CSharp">public static MyClass obj = new MyClass();</sampleCode>
<sampleCode language=“VisualBasic">Public Shared obj As MyClass = New MyClass()</sampleCode>
</item>
</examples>
41. Intel Information Technology
Code samples (external)
Use <code> element with the Source attribute
Can reference existing (live, working) source code
Path is relative to the root documentation project folder
41
<section address="AuthenticationCSharp">
<title>User Authentication Sample</title>
<content>
<code source="..CodeSamplesLoginProgram.cs" language="c#"/>
</content>
</section>
Reference a #region block from the source file
#region may need to be commented in files that do not support them (e.g. Visual
Basic, XAML)
<code source="..CodeSamplesLoginProgram.cs" region="Web Login Example" language="c#"/>
42. Intel Information Technology
Hyperlinks (in topic files)
Referencing external sites
Use the <externalLink> element
42
<externalLink>
<linkText>OAuth</linkText><linkAlternateText>OAuth 2.0</linkAlternateText><linkUri>http://oauth.net/2/</linkUri>
</externalLink>
Referencing topics
Use the <link> element
<para>Section <link xlink:href="463adb15-fc61-41df-b06b-cde0064130a5" /> defines the version history and related changes.</para>
Referencing class members
Use the <codeEntityReference> element
<para>
See <codeEntityReference linkText=“MSDN documentation">M:System.IO.FileStream.Flush</codeEntityReference> for additional info.
</para>
43. Intel Information Technology
Hyperlinks (in XML comments)
Referencing class members
Use the <see> element with the member ID string
43
Referencing topics
Use the <conceptualLink> section element with the topic GUID
Use the <a> HTML element with the topic GUID*
Referencing summary pages
Use the <see> element with the topic ID
Open topic page (in HTML help), right-click and select the View Source
option
Find the <meta name="Microsoft.Help.Id" content="TOPIC ID" /> element
/// <remarks>
/// The value of XYZ is set in the <see cref="M:MyNamespace.MyClass.#ctor(System.String)" alt="class constructor"/>.
/// </remarks>
/// <remarks>
/// See overview of XYZ in the <a href="html/[TOPICFILEGUID]">Introduction</a> section.
/// </remarks>
44. Intel Information Technology
Member ID strings
Format
type:fullname[(arglist)]`genericcount
Types
N (namespase), T (type: class, interface, structure, enum, etc), F (field), E
(event), P (property), M (method), R (root namespace topic [Sandcastle-
specific]), O (overloads list summary [Sandcastle-specific])
Examples
M:Some.ClassX.Format(String,Int)
P:Some.ClassY.Visible
R:MyClassLibrary_Help_File_Name
M:Some.ClassA.op_Explicit(Some.ClassA)~Some.Other.ClassB
44
45. Intel Information Technology
XML comment section elements
<summary>
Keep it brief; do not use lists, tables
<remarks>
Use for more detailed info
<param>
Explain purpose; omit data type (it will be added automatically)
<returns>
Describe return value; omit data type (it will be added automatically), do not
start with a verb
<seealso>, <example>, and more
45
46. Intel Information Technology
<inheritdoc> section element
Allows reusing XML comments
Full or partial
Can be applied to types or individual methods/properties
Use #pragma to disable/enable warning 1573
Format
<inheritdoc [cref="member"] [select="xpath-filter-expr"] />
Inheritance rules
Described in the documentation ("Sandcastle XML Comments Guide")
http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-
e50c66a0221d.htm
46
47. Intel Information Technology
<inheritdoc> section element (continued)
47
#pragma warning disable 1573
/// <inheritdoc cref="Request(AllowedMethods,Object,String,String)" select="returns|param"/>
/// <summary>
/// Calls a web method exposed by the Service Provider with explicitly specified JSON body string and content type.
/// </summary>
/// <param name="body">
/// The body of the request formatted as a JSON string.
/// </param>
/// <param name="contentType">
/// Explicitly defined content type of request, such as <c>application/json;charset=UTF-8</c>.
/// </param>
public RestHttpResponse Request
(
AllowedMethods action,
string body,
string contentType,
string resourceId,
string queryString
)
{
…
}
#pragma warning restore 1573
Example
Reuse descriptions of return value and shared parameters from overloaded
method
48. Intel Information Technology
Resources
"A Coder’s Guide to Writing API Documentation" by Peter Gruenbaum (MSDN
Magazine, November 2010 issue)
http://msdn.microsoft.com/en-us/magazine/gg309172.aspx
"Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code" by
Michael Sorens (Simple Talk, 13 September 2010, Red Gate Software)
https://www.simple-talk.com/dotnet/.net-tools/taming-sandcastle-a-.net-
programmers-guide-to-documenting-your-code/
Includes a demo project and a digital versions of the article (epub, pdf)
"Sandcastle Conceptual Help: Quick Start" by Paul Selormey (Code Project, 30
December 2007)
http://www.codeproject.com/Articles/22539/Sandcastle-Conceptual-Help-Quick-
Start
Includes a demo project
48
49. Intel Information Technology
Documentation
Sandcastle XML Comment Guide
http://www.ewoodruff.us/xmlcommentsguide/html/4268757F-CE8D-4E6D-
8502-4F7F2E22DDA3.htm
Sandcastle MAML Guide
http://www.ewoodruff.us/mamlguide/html/303c996a-2911-4c08-b492-
6496c82b3edb.htm
XML Documentation Comments (C# Programming Guide)
https://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx
49
50. Intel Information Technology
Help and support
Sandcastle Help File Builder discussion forum
https://shfb.codeplex.com/discussions
Sandcastle Help File builder issues
https://shfb.codeplex.com/workitem/list/basic
50
* From “A Coder’s Guide to Writing API Documentation” by Peter Gruenbaum: http://msdn.microsoft.com/en-us/magazine/gg309172.aspx (MSDN Magazine, November 2010)
* From “A Coder’s Guide to Writing API Documentation” by Peter Gruenbaum: http://msdn.microsoft.com/en-us/magazine/gg309172.aspx (MSDN Magazine, November 2010)
There is no option to reference project output in the document sources.
There is no option to reference project output in the document sources.
There is no option to reference project output in the document sources.
There is no option to reference project output in the document sources.
There is no option to reference project output in the document sources.
* From “A Coder’s Guide to Writing API Documentation” by Peter Gruenbaum: http://msdn.microsoft.com/en-us/magazine/gg309172.aspx (MSDN Magazine, November 2010)
I haven't tried this myself (see https://shfb.codeplex.com/discussions/359862)
See additional info in the Sandcastle documentation or at http://www.ewoodruff.us/xmlcommentsguide/html/ee5d612e-914f-411f-bd95-23478b15e4de.htm