Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
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...
Intel Information Technology
Mythbusters
Myth
 Nobody RTFMs
Reality
 True
 End users do not RTFM
 But
 Developers do
...
Intel Information Technology
An awesome manual
Must be
 Short
 Clear
 Comprehensive
Must have
 Code samples
4
Intel Information Technology
Role models (or not)
Founding fathers
 “A well regulated militia being necessary to the secu...
Intel Information Technology
Culture
Richard Dawkins
 “Some people find clarity threatening. They like muddle, confusion,...
Intel Information Technology
Documenting code*
Class
 Start with a word like “Represents”
 “Represents a Windows button ...
Intel Information Technology
Documenting code (continued)*
Event
 Start with a phrase such as “Raised when” or “Occurs wh...
Intel Information Technology
Toolbox
Visual Studio Extensions
 GhostDoc (free)
 Automatically generates XML documentatio...
Intel Information Technology
Sandcastle Help File Builder (SHFB)
About
 Creates help files for managed class libraries co...
Intel Information Technology
Microsoft Assistance Markup Language (MAML)
About
 XML-based markup language
 Used to gener...
Intel Information Technology
Help file options (SHFB)
Formats
 HTML Help 1 (chm)
 MS Help 2 (HxS), MS Help Viewer (mshc)...
Intel Information Technology
Workflow (simplified)
SANDCASTLE PROJECT
CLASS LIBRARY PROJECT
Build process (SHFB)
13
.NET
c...
Intel Information Technology
SHFB process (class library solution)
Steps to build XML documentation file(s)
 Set existing...
Intel Information Technology
SHFB process (SHFB project)
Steps to build documentation
 Add SFHB project to the solution a...
Intel Information Technology
Add SHFB project
16
Intel Information Technology
Configure SHFB project’s Help File settings
17
Intel Information Technology
Configure SHFB project’s Help File settings
(continued)
18
Intel Information Technology
Logo
About
 Logo appears in the page headers
 Supports common image format (.bmp, .gif, .jp...
Intel Information Technology
Define logo
20
Intel Information Technology
Recommended build components
API Token Resolution
 Resolves tokens in XML comments.
Code Blo...
Intel Information Technology
Recommended build components (screenshot)
22
Intel Information Technology
Add document sources to the SHFB project
Include documentation files
 Include XML documentat...
Intel Information Technology
Add document sources to the SHFB project
(screenshots)
24
Intel Information Technology
Visibility settings
Define inclusion/exclusion rules
 Reasonable defaults
 All public membe...
Intel Information Technology
Visibility settings (screenshot)
26
Intel Information Technology
Enter summaries
27
Intel Information Technology
Using tokens for string substitution
Can be used in
 Project properties (summaries)
 Topic ...
Intel Information Technology
String substitution (Content.tokens file)
29
Intel Information Technology
Media files
Add media files to project
 Use the Media folder to store media files
 Final im...
Intel Information Technology
Help file contents
Components of the good API documentation*
 Overview
 Explains what advan...
Intel Information Technology
Content layout
Content.layout file
 Defines topic hierarchy
Every topic
 Must be mapped to ...
Intel Information Technology
Content layout (screenshot)
33
Intel Information Technology
Help file sample (chm)
34
Intel Information Technology
Topic file elements
About
 Context-driven element structure
 Documented in “Sandcastle MAML...
Intel Information Technology
Types of topics
36
Intel Information Technology
Topic file (Conceptual)
37
<?xml version="1.0" encoding="utf-8"?>
<topic id="d522538c-6d28-40...
Intel Information Technology
Topic file (Glossary)
38
<?xml version="1.0" encoding="utf-8"?>
<topic id="01c2aca7-c901-4575...
Intel Information Technology
Code samples (inline)
Use the <code> element with inline code
 Put code inside of the CDATA ...
Intel Information Technology
Code samples (snippets)
Define commonly used code snippets in a .snippets file
 Each snippet...
Intel Information Technology
Code samples (external)
Use <code> element with the Source attribute
 Can reference existing...
Intel Information Technology
Hyperlinks (in topic files)
Referencing external sites
 Use the <externalLink> element
42
<e...
Intel Information Technology
Hyperlinks (in XML comments)
Referencing class members
 Use the <see> element with the membe...
Intel Information Technology
Member ID strings
Format
 type:fullname[(arglist)]`genericcount
Types
 N (namespase), T (ty...
Intel Information Technology
XML comment section elements
<summary>
 Keep it brief; do not use lists, tables
<remarks>
 ...
Intel Information Technology
<inheritdoc> section element
Allows reusing XML comments
 Full or partial
 Can be applied t...
Intel Information Technology
<inheritdoc> section element (continued)
47
#pragma warning disable 1573
/// <inheritdoc cref...
Intel Information Technology
Resources
"A Coder’s Guide to Writing API Documentation" by Peter Gruenbaum (MSDN
Magazine, N...
Intel Information Technology
Documentation
Sandcastle XML Comment Guide
 http://www.ewoodruff.us/xmlcommentsguide/html/42...
Intel Information Technology
Help and support
Sandcastle Help File Builder discussion forum
 https://shfb.codeplex.com/di...
Intel Information Technology
Demo
51
Mailr
 Visual Studio 2013
 Three projects
 Library
 Executable
 Documentation
Intel Information Technology
Questions
52
Contact author
 http://alekdavis.blogspot.com
Upcoming SlideShare
Loading in …5
×

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

6,108 views

Published on

Learn how to build first-class API documentation using Visual Studio 2013 and Sandcastle Help File Builder.

Published in: Software

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

  1. 1. Beyond Comments: How to Build an Awesome API Doc and Be a Better Person Alek Davis Intel
  2. 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
  3. 3. Intel Information Technology Mythbusters Myth  Nobody RTFMs Reality  True  End users do not RTFM  But  Developers do – Self – Peers – Customers 3
  4. 4. Intel Information Technology An awesome manual Must be  Short  Clear  Comprehensive Must have  Code samples 4
  5. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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
  16. 16. Intel Information Technology Add SHFB project 16
  17. 17. Intel Information Technology Configure SHFB project’s Help File settings 17
  18. 18. Intel Information Technology Configure SHFB project’s Help File settings (continued) 18
  19. 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
  20. 20. Intel Information Technology Define logo 20
  21. 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
  22. 22. Intel Information Technology Recommended build components (screenshot) 22
  23. 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
  24. 24. Intel Information Technology Add document sources to the SHFB project (screenshots) 24
  25. 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
  26. 26. Intel Information Technology Visibility settings (screenshot) 26
  27. 27. Intel Information Technology Enter summaries 27
  28. 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>
  29. 29. Intel Information Technology String substitution (Content.tokens file) 29
  30. 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. 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. 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
  33. 33. Intel Information Technology Content layout (screenshot) 33
  34. 34. Intel Information Technology Help file sample (chm) 34
  35. 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
  36. 36. Intel Information Technology Types of topics 36
  37. 37. Intel Information Technology 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>
  38. 38. Intel Information Technology Topic file (Glossary) 38 <?xml version="1.0" encoding="utf-8"?> <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> <glossaryEntry>[…]</glossaryEntry> <glossaryEntry>[…]</glossaryEntry> </glossary> </developerGlossaryDocument> </topic>
  39. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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
  51. 51. Intel Information Technology Demo 51 Mailr  Visual Studio 2013  Three projects  Library  Executable  Documentation
  52. 52. Intel Information Technology Questions 52 Contact author  http://alekdavis.blogspot.com

×