Documenting overloaded methods and Sandcastle
I'm a bit of a newbie using Sandcastle, so please bear with me. I'm at a lost. I cannot find out how to document the collection of overloaded methods.
For instance. Say I have four overloaded Add() methods:
public
void Add(string name)public
void Add(string name,Socket socket)public
void Add(Socket socket, RobotPart robotpart)public
void Add(string name,Socket socket, RobotPart robotpart)It looks to me as though Sandcastle, by default creates a folder for all of these Add() methods, and randomly chooses one of the headers as the folder name (again please bear with me about the names I am using)
Now, within a summary tag for another method, say GetSomething(), I want to place a tag which will reference that folder, not any one particular method.
/// <summary>
/// Do something calls the <see cref="Add">Add()</see> method and does something.
/// </summary>
private void DoSomething()
{}
I would think that this should work, but I get a warning as error:
Error 1 Warning as Error: XML comment on 'DoSomething' has cref attribute 'Add()' that could not be resolved
[2042 byte] By [
Sweeps78] at [2007-12-26]
There's a bug in the transformation that causes the first overload to get used as the table of content name. Hopefully, that'll be fixed in the next CTP due out at the end of this week.
To get it to reference the overload topic itself, you'll have to suppress that specific warning number in the project options or with a #pragma statement. When done that way, NDoc would reference the overload topic but I haven't tried it with Sandcastle so I don't know if it will work for sure.
Eric
How do I specify the overloaded method in the XML comments though?
If you want to reference a specific overload, you can specify the parameters too:
/// Do something with <see cref="Add(string)"/> or <see cref="Add(Socket, RobotPart)"/>.
Eric
Thanks, but how do I reference the main folder (which Sandcastle creates) containing all the overloads?
Do it like you have in the original post (<see cref="Add"/>) and as I said in my first reply:
To get it to reference the overload topic itself, you'll have to suppress that specific warning number in the project options or with a #pragma statement. When done that way, NDoc would reference the overload topic but I haven't tried it with Sandcastle so I don't know if it will work for sure.
Eric
We have fixed this bug and will provide a drop this weekend. Cheers.
Anand..
excellent! I can't wait to check it out.
Thank you:)
Hi,
I just installed the November CTP, and am trying to process a tag such as the following, where myOverloadedMethod is overloaded:
<seealso cref="myOverloadedMethod"/>
I'm noticing that the VS2005 C# editor is automatically assuming a particular set of parameters for the method, without giving me any warning that I could turn off (as recommended in a previous message in this thread). In fact, if I pass the mouse pointer over the identifier "myOverloadedMethod" in my C# source, I get an IntelliSense-style message reporting "Ambiguous reference in cref attribute" with the particular overload that is being assumed. But I don't see any warning number associated with this message.
I'm not aware of any setting in my project that could be causing the automatic resolution of the ambiguous name. Is there any way to bypass it and explicitly request a reference to the summary topic for the overload?
Thanks!!
Sue
If the tag in the xml documentation file produced by C# compiler is modified to read:
<seealso cref="Overload:myNamespace.myOverloadedMethod"/>
then sandcastle will create a correct link to the overload page.
However, I don't know of any way of making the compiler emit such a cref style reference starting with "Overload:".
It is possible to get any single letter (I think) followed by a colon. E.g. if the source reads:
/// <seealso cref="O:myNamespace.myOverloadedMethod"/>
this will produce
<seealso cref="O:myNamespace.myOverloadedMethod"/>
in the xml documentation file.
[Note: any cref starting with "X:", where X is any single letter, is not checked for validity by the compiler. It is just passed through, unchecked.]
I think (but I haven't tried it) that it is a simple mod to Sandcastle so that it names it's overloads with "O:xxx" instead of "Overload:xxx". Then I think this would have the problem solved.
[Note: you are correct about the behaviour of <seealso cref="myOverloadedMethod"/>... The compiler always assumes one of the overloads (always the first?) so you never get a reference to anything like an 'overloads' node.]
David
Many many thanks for the helpful information! To test my understanding, I experimented a little, with the following results.
Linking to a specific overload of the method
If I enter the following in my C# source code:
<see cref=myOverloadedMethod/> the compiler produces the following output in the generated XML file:
<see cref=M:MyNamespace.MyClass.myOverloadedMethod(someParameters)/> and Sandcastle generates a link to the topic for the specific overload.
Linking to the method's general overload topic
If I add a prefix 'Overload' and add qualification to the method name in my C# source code:
<see cref=Overload:MyNamespace.MyClass.myOverloadedMethod/> the compiler produces the following output in the generated XML file:
<see cref=!:Overload:MyNamespace.MyClass.myOverloadedMethod/> I can then run a script to change each instance of !:Overload: to Overload:. Sandcastle can now generate a link to the general overload topic for the method.
Alternative way to link to a general topic (could use a Sandcastle modification)
If I add a prefix 'O' and add qualification to the method name in my C# source code:
<see cref=O:MyNamespace.MyClass.myOverloadedMethod/>
the compiler passes it through as is to the generated XML file:
<see cref=O:MyNamespace.MyClass.myOverloadedMethod/>
I can then run a script to change each instance of O: to Overload:. Sandcastle can now generate a link to the general overload topic for the method.
However, no script would be necessary if Sandcastle could interpret O: as equivalent to Overload:. (That would be lovely...)
Thanks,
Sue
Sue,
Your analysis is exactly correct as far as I can tell.
I have modified the Sandcastle scripts to intercept cref="O:..." and generate cref="Overload:..." style links and this works perfectly.
[Note: This solution was easier than changing all "Overload:" instances to "O:" in all scripts... there are quite a few of these and also there is one important one that seems to be hard coded inside the dll component which resolves the reference links... so I can't change that.]
I will post my solution later (which also allows the text to be specified for all cref style references [e.g. <see cref="foo">MyCustomLinkText</see>]). Currently I am not at my desk-top system where the solution is filed.
David
The following mod to Sandcastle allows overload nodes to be specified in C# with
/// <see cref="O:myNamespace.myClass.myOverloadedMember"/>
[Note: The fully qualified name must be used and the compiler does not check for validity.]
This mod also allows custom text to be specified for cref style links:
/// <see cref="myMember">my custom text</see>
You need to make two changes to main_sandcastle.xsl (which occurs both in Prototype and vs2005).
1. Find in the following code:
<xsl:template match="see[@cref]">
<referenceLink target="{@cref}" />
</xsl:template>
And modify it to:
<xsl:template match="see[@cref]">
<xsl:choose>
<xsl:when test="starts-with(@cref,'O:')">
<referenceLink target="{concat('Overload:',substring(@cref,3))}">
<xsl:apply-templates />
</referenceLink>
</xsl:when>
<xsl:otherwise>
<referenceLink target="{@cref}">
<xsl:apply-templates />
</referenceLink>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
2. Similarly find:
<xsl:template match="seealso">
<referenceLink target="{@cref}" />
</xsl:template>
And modify it to:
<xsl:template match="seealso">
<xsl:choose>
<xsl:when test="starts-with(@cref,'O:')">
<referenceLink target="{concat('Overload:',substring(@cref,3))}">
<xsl:apply-templates />
</referenceLink>
</xsl:when>
<xsl:otherwise>
<referenceLink target="{@cref}">
<xsl:apply-templates />
</referenceLink>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
David
Wow, this does the trick! Many, many thanks!!
Any chance of this being built into standard Sandcastle?
Sue
Yes and we certainly can. Thanks David.
Anand..
