Linking to Constructors

Feb 27, 2008 at 2:32 AM
Is there a way of linking to constructors and constructor overloads with Sandcastle?

Back in the days of NDOC, I could do something like this:

/// <see href="Test.Info.MyClassConstructor.html">constructor</see>

where "Test.Info.MyClass" is the fully-qualified name of the class whose constructor is to be referenced. The link would be to the constructor overloads page if the constructor had overloads or otherwise to the single constructor page. This does not work with Sandcastle with Sandcastle Help File Builder.

In the thread Linking to Overloads in this forum, I asked a related question, how to link to overloads with Sandcastle. After some discussion, I got enough information for a good answer. I suspect that the answer to the question I'm asking in this thread is related.

Feb 27, 2008 at 3:20 AM
Hi Simon,

To link to an explicit constructor simply use the type name with parenthesis:

/// <summary>
/// See the <see cref="MyType()">constructor without arguments</see>.
/// See the <see cref="MyType(string)">constructor with one argument</see>.
/// </summary>
public class MyType
  /// <summary>This is the constructor without arguments.</summary>
  public MyType() { }
  /// <summary>This is the constructor with one argument.</summary>
  public MyType(string s) { }
As for linking to overloads, the answer is going to be the same as for the question in your other thread.

- Dave
Feb 27, 2008 at 3:21 AM
Edited Feb 27, 2008 at 3:22 AM
Linking to a particular constructor is just like linking to any other method:

<see cref="TestClass()"/>
<see cref="TestClass(string, int)"/>

I'm guessing that linking to the overloads page would be done in a similar fashion as to the way it's done in the thread you reference. The key for the topic would be "Overload:TestDoc.TestClass.#ctor" so you'd just need to come up with a filename for it.


[EDIT: Beat me by a few seconds there Dave :)].
Feb 27, 2008 at 9:40 PM
Thanks to Dave's and Eric's suggestions, I have got this working. I have experimented with a small test project and the following is what I found.

For a class with a single constructor, the constructor can be referenced with or without its parameter types in parentheses, like these:

<see cref="TestClass"/>
<see cref="TestClass(string, int)"/>
For a class with overloaded constructors, the constructor overloads page can be referenced with the "O:" prefix and the fully qualified class name and the ".#ctor" suffix, like this:

<see cref="O:TestNamespace.ClassWithConstructorOverloads.#ctor"/>
That method for referencing the constructor overloads page works provided main_sandcastle.xsl has been modified as per the instructions in the Linking to Overloads thread.

Of course, in all of the above examples it would probably have been better to add the word "constructor" or "constructors" or similar as custom text, like these:

/// This is specified in the <see cref="TestClass">constructor</see>.
/// This is specified in the <see cref="TestClass(string, int)">constructor</see>.
/// This is specified in the <see cref="O:TestNamespace.ClassWithConstructorOverloads.#ctor">constructor</see>.
Otherwise the documentation to be generated would look a little odd. For example, I would want the first sentence generated from the code snippet above to read "This is specified in the constructor.", not "This is specified in the TestClass.".

Thanks again, Dave and Eric, for your help.

Feb 28, 2008 at 1:33 AM
Hi Simon,

Thanks for the update.

I think your first example is wrong though - you'll need parenthesis even when there are no constructor arguments; otherwise, the link will point to the type itself.

<see cref="TestClass()"/>
<see cref="TestClass(string, int)"/>
- Dave
Feb 28, 2008 at 3:24 AM
Hello Dave,

Oops! Yes, you are right. I had not noticed that.