Beyond Comments: How to Build an Awesome API Doc and Be a Better Person

Beyond Comments:
How to Build an Awesome API Doc and Be a
Better Person
Alek Davis
Intel

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

Mythbusters
Myth
 Nobody RTFMs
Reality
 True
 End users do not RTFM
 But
 Developers do
– Self
– Peers
– Customers
3

An awesome manual
Must be
 Short
 Clear
 Comprehensive
Must have
 Code samples
4

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

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

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

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

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

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

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

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

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

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

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

Add SHFB project
16

Configure SHFB project’s Help File settings
17

Configure SHFB project’s Help File settings
(continued)
18

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

Define logo
20

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

Recommended build components (screenshot)
22

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

Add document sources to the SHFB project
(screenshots)
24

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

Visibility settings (screenshot)
26

Enter summaries
27

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>

String substitution (Content.tokens file)
29

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>

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

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

Content layout (screenshot)
33

Help file sample (chm)
34

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

Types of topics
36

Topic file (Conceptual)
37
<?xml version="1.0" encoding="utf-8"?>
<topic id="d522538c-6d28-40fa-bd4b-60378c290749" revisionNumber="1">
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction><para>This document describes the <token>PRODUCTNAME</token> API.</para></introduction>
<section>
<title>Topics</title>
<content>
<para>The document covers the following topics:</para>
<list class="bullet">
<listItem>
<para><link xlink:href="5f1909f4-0463-4215-9bb1-3ad3e8568c7e"/> offers introduction to
<token>PRODUCTNAME</token>.[…]</para>
</listItem>
<listItem>[…]</listItem>
<listItem>[…]</listItem>
</list>
</content>
</section>
<section>[…]</section>
<relatedTopics>
<link xlink:href="01c2aca7-c901-4575-a3ea-2afccc562162"/>
<link xlink:href="1c88eaef-469d-49ce-8a23-60364fa2b69d"/>
<link xlink:href="7001063d-2637-4b8c-8b0a-a482018c9a89"/>
</relatedTopics>
</developerConceptualDocument>
</topic>

Topic file (Glossary)
38
<topic id="01c2aca7-c901-4575-a3ea-2afccc562162" revisionNumber="1">
<developerGlossaryDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<glossary>
<title>Glossary</title>
<glossaryEntry>
<terms><term termId="IAM">IAM</term><term>IdAM</term></terms>
<definition>
<para>IAM (or IdAM) stands for Identity and Access Management.</para>
</definition>
</glossaryEntry>
<glossaryEntry>[…]</glossaryEntry>
</glossary>
</developerGlossaryDocument>
</topic>

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>

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>
<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>

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#"/>

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>

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>

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

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

<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

<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

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

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

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

Demo
51
Mailr
 Visual Studio 2013
 Three projects
 Library
 Executable
 Documentation

Questions
52
Contact author
 http://alekdavis.blogspot.com

Beyond Comments: How to Build an Awesome API Doc and Be a Better Person

More Related Content

What's hot (20)

Similar to Beyond Comments: How to Build an Awesome API Doc and Be a Better Person (20)

Recently uploaded (20)

Beyond Comments: How to Build an Awesome API Doc and Be a Better Person

Editor's Notes