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

http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748

http://visualstudiogallery.msdn.microsoft.com/a23de100-31a1-405c-b4b7-d6be40c3dfff


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

https://shfb.codeplex.com/


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

compilerHelp 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

http://msdn.microsoft.com/en-us/library/vstudio/x4sa0ak0(v=vs.100).aspx


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 componentsAPI 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 layoutContent.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 elementsAbout

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

<developerConceptualDocumentxmlns="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

<?xml version="1.0" encoding="utf-8"?><topic id="01c2aca7-c901-4575-a3ea-2afccc562162" revisionNumber="1">

<developerGlossaryDocumentxmlns="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><glossaryEntry>[…]</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>

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


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="..\CodeSamples\Login\Program.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="..\CodeSamples\Login\Program.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 stringsFormat

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

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm


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

http://msdn.microsoft.com/en-us/magazine/gg309172.aspx

https://www.simple-talk.com/dotnet/.net-tools/taming-sandcastle-a-.net-programmers-guide-to-documenting-your-code/

http://www.codeproject.com/Articles/22539/Sandcastle-Conceptual-Help-Quick-Start


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

http://www.ewoodruff.us/xmlcommentsguide/html/4268757F-CE8D-4E6D-8502-4F7F2E22DDA3.htm

http://www.ewoodruff.us/mamlguide/html/303c996a-2911-4c08-b492-6496c82b3edb.htm

https://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx


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

https://shfb.codeplex.com/discussions

https://shfb.codeplex.com/workitem/list/basic


Demo

51

Mailr

Visual Studio 2013

Three projects

Library

Executable

Documentation


Questions

52

Contact author

http://alekdavis.blogspot.com

http://alekdavis.blogspot.com/

beyond comments: how to build an awesome api doc and be a better person

Software

meaningful api documentation

xml documentation comments

awesome api doc

spelling of comments

coders guide

microsoft visual studio

windows button control

specified key