Click here to Skip to main content
Click here to Skip to main content

Tagged as

Authoring/Integrating API Help for VS2008 and VS2010

, 19 May 2010 CPOL
Rate this:
Please Sign up or sign in to vote.
Create context-sensitive help files for your own APIs

Introduction

From time to time, I have had to develop APIs that are used by other developers inside and outside of my organization. It has always been my thought to be able to package it up with nice documentation and professional looking help files. Through some freely available tools, it is fairly easy to generate professional looking help files, but I always seemed to get stuck on integrating it with the VS IDE. In this article, I will show how I solved the problem for both VS2008 and the new Help3.x format for VS2010.

The Tools You Will Need

And, of course, you will need either or both of Visual Studio 2008/2010.

Sample API

public class API
{
	public API()
	{
	}

	public string Foo( string s )
	{
		return "Foo got " + s;
	}
}

GhostDoc

The GhostDoc project is a free VS plug-in that greatly simplifies generating the XMLDoc comments in your API source code. As you define and implement your classes, it is pretty trivial to create these comments within VS by simply typing three '/'s, giving you:

/// <summary>
/// 
/// </summary>
public class API
{
	/// <summary>
	/// 
	/// </summary>
	public API()
	{
	}

	/// <summary>
	/// 
	/// </summary>
	/// <param name="s"></param>
	/// <returns></returns>
	public string Foo( string s )
	{
		return "Foo got " + s;
	}
}

This is very helpful, but there can be a lot of hand-editing that would be required in filling in all of these values. Then there's always the problem of trying to remember the formats for type references inside of the comment blocks, etc.

GhostDoc helps this by providing a "Document this" context-menu inside of VS:

authoring1.png

The result is a much more friendly:

/// <summary>
/// Initializes a new instance of the <see cref="API"/> class.
/// </summary>
public API()
{
}

The embedded <see.../> tag will generate live link references to other parts of the documentation once it is generated (rather than just the text). Another nice feature of GhostDoc is that it will intelligently pull the docs from a base class or interface if there is one there to use:

/// <summary>
/// Returns a <see cref="System.String"/> that represents this instance.
/// </summary>
/// <returns>
/// A <see cref="System.String"/> that represents this instance.
/// </returns>
public override string ToString()
{
	return base.ToString();
}

Sandcastle

The Sandcastle project will aid in taking those doc comments and turn them into API documentation. First, in order to generate the documentation, you need to generate the XML documentation file in the project's Build Output options:

authoring2.png

This generated file (along with the actual DLL file) is the input that Sandcastle needs to do its magic. Open the Sandcastle Help File Builder GUI and create a new project:

authoring3.png

Now we add our generated XML file from Visual Studio to the project:

authoring4.png

As shown here:

authoring5.png

To generate help files for VS2010, select HelpFileFormat "MSHelpViewer":

authoring6.png

This will cause Sandcastle to generate a file (by default: Documentation.mshc).

To generate help files for VS2008, select "MSHelp2". This will cause Sandcastle to generate a series of files (*.HxS, *.HxC, etc.).

These are our raw help files that we now need to integrate into the IDEs.

While we are at this point, I want to point out that you can also select "HtmlHelp1" to generate the venerable *.chm (compiled HTML) help file. However, this cannot be integrated into either IDE, but it useful for distributing with your code inside an MSI, accessible from a Start menu entry, for example. The fourth option is to generate HTML documentation. If you want to host your documentation on a web server or zip it up to distribute with your API, this is another option from Sandcastle.

MSHC Migrate Utility

This is a commercial utility from Helpware that will allow you to migrate to the new VS2010's Help3.x format from several other formats. It is not free. I include it here, simply for completeness.

All we really need to integrate our generated *.mshc file into VS2010 is a help manifest file (*.msha) as shown:

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>My API's Manifest</title>
</head>
<body class="vendor-book">
  <div class="details">
    <span class="vendor">Me</span>
    <span class="locale">en-us</span>
    <span class="product">My API</span>
    <span class="name">My API</span>
  </div>
  <div class="package-list">
    <div class="package">
      <span class="name">TestAPI</span>
      <a class="current-link" href="Documentation.mshc">Documentation.mshc</a>
    </div>
  </div>
</body>
</html>

The important entries here are making sure the Package-list section points to your generated documentation file (*.mshc), and that the <span ...>TestAPI</span> value points to the outermost namespace of your API. Save this file in the same directory as your *.mshc file and name it "helpcontentsetup.msha".

Now you are ready to integrate this with VS2010. You need to start VS2010 with Administrative privileges (right-click the icon or menu, and select "Run as administrator"). You will know you are running as Administrator because the title bar of VS will say "(Administrator)". Next select Help -> Manage Help Settings to start the Help Library Manager as shown:

authoring7.png

Select "Install content from disk" and browse to your newly created manifest file "helpcontentsetup.msha" and select it. This will show you your new API documentation, select "Add" and click the Update button to integrate it with the installed help files, as shown:

authoring8.png

Viola! Your API is now registered with the local help files of VS2010.

authoring9.png

To integrate with VS2008, we need to create a VS Extension installer. Add to your solution a new project (under Other Project Types -> Extensibility) a new Help Integration Wizard project. This can be either as a setup project or a merge module. In the wizard, simply step through the options and when you get to Source Files, add the *.HxS file we generated with Sandcastle.

Building and installing the resulting MSI will add the new help files to the locally installed help.

Note that in VS2008, after installing your MSI the first time you access the help system it will have to update itself, which will take a few minutes (a crazy long amount of time in my experience ... sigh).

authoring10.png

Additional documentation for each of the tools mentioned is available on their respective web sites.

History

  • 19th May, 2010: Initial post

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Derek Viljoen
Software Developer (Senior)
United States United States
Developer with over twenty years of coding for profit, and innumerable years before that of doing it at a loss.

Comments and Discussions

 
GeneralIf you like my article, you'll love this one. PinmemberDerek Viljoen15-Nov-10 5:32 
QuestionSupport F1 for custom language PinmemberDaisydale26-Jul-10 19:15 
AnswerRe: Support F1 for custom language PinmemberDerek Viljoen27-Jul-10 4:04 
GeneralBetter info on the Manifest file... PinmemberDerek Viljoen20-May-10 15:29 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web04 | 2.8.141030.1 | Last Updated 19 May 2010
Article Copyright 2010 by Derek Viljoen
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid