<see /> for overloaded method?

Topics: Developer Forum, User Forum
Jun 13, 2009 at 1:02 AM

Sorry if this is a dumb question; couldn't find anything on it in the documentation...

I have an overloaded method, and I want to make a <see /> link that goes to the overload's overview page.  I coded the XML tag in my code like so:

 

... <see cref="MyNamespace.MyClass.MyOverloadedMethod">MyOverloadedMethod</see> ... 

 

However, I get an"Ambiguous reference in cref attribute" warning on this from Visual Studio, and after SHFB builds the CHM, the resulting link goes to the MyOverloadedMethod() entry (the overload with no parameters). 

Is there a way to construct the tag so that the link goes to the MyOverloadedMethod overview page?

Coordinator
Jun 14, 2009 at 1:09 AM

This has already been discussed several times.  See these threads for a possible solution:

http://social.msdn.microsoft.com/Forums/en-US/devdocs/thread/3906970c-4825-492b-8536-8bf644b46648/

http://www.codeplex.com/Sandcastle/Thread/View.aspx?ThreadId=22348

Eric

 

Jun 16, 2009 at 6:10 PM
Edited Jun 16, 2009 at 6:11 PM

 

I got it working, thanks for the pointers!  

It took me a while to figure it all out, so for the benefit of those who come across this thread in the future, here is what I did:

My project had the default value for Help File | Naming Method: Guid. I changed this to MemberName.

My project had the default value for Help File | ProjectLinkType: Local. I left this as-is.

I temporarily changed the value of Build | CleanIntermediates to False.

I built the help file and checked in the Paths | WorkingPath location. Here, in the Output\html folder, I located the HTML file that corresponded to
the overview page for MyOverloadedMethod: Overload_MyNamespace_MyClass_MyOverloadedMethod.htm

I went back to my .Net project and tweaked my <see /> tag to use an href instead of a cref and to point to the overview page:

... <see href="Overload_MyNamespace_MyClass_MyOverloadedMethod.htm">MyOverloadedMethod</see> ... I rebuilt the .Net project to regenerate the XML documentation.

In the help project, I changed the value of Build | CleanIntermediates back to True.

I built the help file.

Presto!

 

 

Coordinator
Jun 16, 2009 at 8:04 PM

Good idea.  I'd forgotten about the href attribute support on the <see> tag.

Eric

 

Jun 16, 2009 at 9:18 PM

Oh...is there another approach that is better?  I thought I ended up with the approach everyone seemed to be talking about ;)

Coordinator
Jun 17, 2009 at 3:17 AM

Sorry, what you've got works.  I was more focused on the XSL change which is what I searched for and didn't notice that the thread in the second link showed how to do the href thing.  As I mentioned, I'd forgotten about that :).  The XSL transformation modification might be easier to use since you wouldn't have to look up the names.  You'd have to remember to apply it to Sancastle when a new release comes out is all.  However, if you post a work item in the Sancastle Styles project, we could add it to that.

Eric

 

Jun 17, 2009 at 6:47 PM

Ok, I see it now.  That was part of the problem with sorting out the info in those threads.  I found it difficult to separate the two lines of thought, and I latched onto the href method and thereafter disregarded the other stuff as noise.

It does look cleaner to tweak the XSL, but I'm reluctant to put something in place that I'd have to remember to retweak down the line when I upgrade and something silently breaks.  Better (for me) to avoid that gotcha.

I am a bit confused, though.  You suggested that I could put this in as a work item, but those threads are quite old and in them somebody said they were going to put those changes in.  Something that just keeps falling through the cracks I guess?

Apr 12, 2011 at 7:13 PM

Wow! I can't believe this feature still isn't implemented. I tried <see cref="Overload:Namespace.Class.MethodName"/> and <see cref="O:Namespace.Class.MethodName"/>; neither of them work.

I also can't figure out how to share documentation between all overloads. <inheritdoc/> doesn't work for me. Shouldn't it be the default to share documentation? It's ridiculous to have to manually copy the same summary and remarks for every overload, and a nightmare to keep changes synchronized.

Coordinator
Apr 12, 2011 at 8:45 PM

The inheritdoc tag only inherits from base class members of the same signature.  It won't work with overloads without giving it a hint using the cref attribute.  With that, you can inherit documentation from any member even those outside the class in question.  See the inheritdoc help topic for more information.  Regarding <see> for overloads, that's something that has to be implemented in the Sandcastle XSL transformations so it's not something you will see implemented by SHFB.

Eric

 

Apr 13, 2011 at 1:03 AM
Edited Apr 13, 2011 at 4:20 PM

Thanks. For anybody reading this wondering how to use inheritdoc, put this in front of each overload of your method except the one with the real documentation: /// <inheritdoc cref="MethodName(list of parameter types for the overload that has the documentation)"/>

In order to support the syntax cref="O:Namespace.Class.MethodName", I made the following script (called FixOverloadRefs.bat - requires powershell to be installed).

@@:: This prolog allows a PowerShell script to be embedded in a .BAT file. Credit: Jay Bazuzi
@@setlocal
@@set PS_BAT_ARGS=%*
@@if defined PS_BAT_ARGS set PS_BAT_ARGS=%PS_BAT_ARGS:"=\"%
@@PowerShell -Command Invoke-Expression $('$args=@(^&{$args} %PS_BAT_ARGS%);'+[String]::Join(';',$((Get-Content '%~f0') -notmatch '^^@@'))) & goto :EOF
(cat $args[0] | % { $_ -replace 'cref="O:', 'cref="Overload:' }) | Out-File -Encoding UTF8 $args[0]

Then I invoke the script using the following Post-build event command line: (Project settings | Build events)

$(ProjectDir)FixOverloadRefs.bat $(TargetName).xml

Jul 12, 2013 at 3:00 AM
Edited Jul 12, 2013 at 3:03 AM
I found that selecting the Fix up method signature issues in C++ XML comments files check box on SHFB's Build tab lead to the successful rendering of <see cref="Overload:Namespace.Class.MethodName"/> links (in source code), in the generated help output.

This actually worked for some C# code I'm documenting thru Visual Studio 2012, using SHFB 1.9.7.0.