Overloads

Jan 31, 2009 at 5:58 PM
Hi! Great product; it's very useful!

I've been working on some problems regarding <overloads>.

The first one is simple (how to link a <see> to an overloads page) - I'm just using O:[member] and running an xslt script to change O: to Overload:. Works like a charm, but I am a little surprised SHFB didn't handle it with the default install.

My second question is more involved: I have three overloaded functions that should all have identical <summary> and <remarks>, and these should be duplicated on the overloads page as well. However, when I add the <overloads> tag (with <summary> and <remarks> children), it only shows up on the overloads page. I could inherit the documentation for the other functions using <inheritdoc>, but it won't let me for the function that includes <overloads> - InheritedDocumentation throws "Circular reference detected." Which is true - it's referring to itself - but it has a selection to prevent recursion.

Is there any way to make this work, other than using <include>? (There's no external documentation files in my project at this time).

       -Steve
Coordinator
Jan 31, 2009 at 8:42 PM
The <see> elements are handled by the Sandcastle transformations not SHFB.  I think other people have come up with similar workarounds by modifying them directly to handle references to overloaded members (see http://social.msdn.microsoft.com/Forums/en-US/devdocs/thread/3906970c-4825-492b-8536-8bf644b46648/).

The <overloads> tag is only processed for the Overloads page.  Its content won't appear on any other member.  The solution to your problem would be to put the documentation on one of the overloaded members except the one with the <overloads> tag and then use <inheritdoc> on the other members and inside of the <overloads> tag to inherit from the specific overload that contains the comments.

Eric
Jan 31, 2009 at 10:21 PM

Oh, man, I have no idea why I didn't think of that solution for <overloads>. Must be tired... Thanks so much!

Regarding the <see> problem, I did find that thread, did several tests on what was currently supported, and settled on the separate xslt solution. For the record, an ambiguous cref reference will resolve to a specific function instead of the overloads page (based on the wording of CS0419, I suspect the compiler rather than Sandcastle is doing this). Perhaps now that the Sandcastle source has been released, an "O:"-based workaround may become available.

And thank you for developing such an awesome tool! Seriously, I used to use HTML Help Workshop by hand years ago... SHFB is to C# as HTML Help Workshop is to assembler. :)

Keep up the good work!

      -Steve