DocProject Tips and Tricks

DocProject with Sandcastle are a great choice for creating MSDN-style documentation. You can author conceptual documentation using MAML (Microsoft Assistance Markup Language) and reference documentation from managed assemblies and XML comments. Here is the documentation for DocProject. Writing conceptual documentation I ran into some problems that were not straight forward to solve. Hopefully these tips will help you if you have the same problems.

Overloaded Methods
The codeEntityReference tag allows you to link to API reference documentation (namespaces, types, methods, properties, fields). You have to prefix the fully qualified name of the entity with N: for namespaces, T: for types, P: for properties, F: for fields and M: for methods. What if you have overloaded methods and you want to link to the page that displays all of them, not one particular method? The O: prefix Visual Studio is expecting (for XML comments) does not work. Sandcastle Help File Builder (SHFB) expects Overload: instead.

Methods with arguments
If you want to link to API reference documentation for a method that take some parameters you must specify those parameter’s type in parenthesis.

However, if the method takes more than one parameter, you must separate the argument types with a comma and use no whitespaces between them. If you have whitespaces the API reference will not be resolved.

Constructors
Constructors are special methods so you must use a special notation for them: instead of using their name use the #ctor tag.

Of course, if the constructor has some arguments you must specify them in parenthesis:

Generics
When it comes to generics you must use the special notation with ` (grave accent). The grave accent (`) indicates the level and the number after it is the number of the generic types. Here are the rules (as indicated in the ECMA specification ):

  • Arguments that define generic type parameters have an appended grave accent character followed by the number of type parameters (ex. T`1)
  • For nested types, the number is based upon the of new type parameters on the nested type(ex. T`1.Nested`2)
  • Arguments that refer to generic type parameters on types are encoded using a single grave accent character (`) followed by the zero-based index of the type parameter.
  • Arguments that use generic parameters on methods use double grave accent characters (``) followed by the zero-based index of the type-parameter instead of the single grave accent used for parameters on types.

For instance, let’s say your class looks like this:

If you want to link to the generic bar type you must do it like this:

What if you had a generic method too?

Then you must refer to the function as follows:

API Reference Documentation
When you author documentation you probably want to put together conceptual documentation and API reference documentation. The later you build from external sources, i.e. assemblies and XML files with the XML-comments you wrote in the source code. Question is where and how do you insert this API reference? The answer was not very easy to find; luckily a colleague of mine was able to help me with the answer.

First of all, there is only one place in the hierarchy of your topics hierarchy where you can insert it. So no matter from how many sources you build this, it all goes into one place. To set the place you must edit the topics.xml file (under Help\Settings). This file looks like this (of course, this is a dummy sample):

There is a special tag you can insert as a child of a topic. It’s called stoc and looks like this:

This will tell the builder to insert under topic1 all the API reference documentation.

2 Replies to “DocProject Tips and Tricks”

  1. Thanks for the article and the post at Code Project. Quick question: what’s the benefit of using DocProject with Sandcastle vs. just using Sandcastle? I have used HTML Help, nDoc, and Sandcastle, but I haven’t spent much time with DocProject. I glanced over the intro documentation page, but still a bit hazy. What does DocProject do that Sandcastle can’t?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.