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

4,987 views

Published on

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

Published in: Software
1 Comment
4 Likes
Statistics
Notes
No Downloads
Views
Total views
4,987
On SlideShare
0
From Embeds
0
Number of Embeds
1,857
Actions
Shares
0
Downloads
27
Comments
1
Likes
4
Embeds 0
No embeds

No notes for slide
  • * 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)
  • Use the UTF-8 “\xA9” code for the copyright © symbol in the Copyright notice text.
  • 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
  • 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

    ×