Automatically dealing with overloads

Apr 12, 2011 at 6:52 PM
Edited Apr 12, 2011 at 6:53 PM

Hi, I'd like to tweak the way Sandcastle deals with overloads, because I'd prefer not to manage duplicate copies of the same documentation, or even manage <inheritdoc/> tags manually.

I want to be able to share one documentation page with all overloads. So the following code:

/// <summary>
/// Launches the freakin' space shuttle.
/// </summary>
/// <param name="destination">Destination expressed as documented in RFC 3514.</param>
/// <param name="launchTime">When to launch.</param>
/// <param name="countDown">Time to launch expressed as an offset from the
/// current time.</param>
/// <exception cref="NotSupportedException">Space shuttle is no longer in service.</exception>
/// <remarks>
/// This method may cease to function after June 28, 2011.
/// If launchTime or countDown parameters are omitted, 
/// the shuttle launches immediately.
/// </remarks>
void LaunchShuttle(Uri destination, DateTime launchTime) { ... }
void LaunchShuttle(Uri destination, TimeSpan countDown) { ... }
void LaunchShuttle(Uri destination) { ... }

Should produce the same page for each overload except that parameters that do not apply are left out.

Naturally, I want <see cref="LaunchShuttle"/> to create a link to all overloads, not just a random overload. I know that the C# compiler randomly picks an overload for some reason, but maybe an extra attribute (e.g. <see cref="LaunchShuttle" mode="specific"/>) could express whether a specific overload or all overloads is desired. (To make life easier, the default should be "all").

How could I modify Sandcastle to make this happen (or even use one identical page for all overloads)? Keeping in mind that I'm a noob.

Bonus points if you know how to make the overload page only state the summary once, not pointlessly repeated for every overload.

Apr 12, 2011 at 7:02 PM
Edited Apr 12, 2011 at 7:06 PM

P.S. For inherited members in the "class members" list, I'd like to use a light gray background color for inherited methods and light yellow for protected methods. Listing the protected and inherited members last would also be nice. How hard would that be?

Apr 12, 2011 at 7:27 PM
qwertie wrote:

P.S. For inherited members in the "class members" list, I'd like to use a light gray background color for inherited methods and light yellow for protected methods. Listing the protected and inherited members last would also be nice. How hard would that be?

The current way is to use icons as in the MSDN, and if that is not sufficient for your needs,
you will have to modify the Sandcastle presentation styles to have this.

Best regards,
Paul. 

Apr 12, 2011 at 7:55 PM

>>qwertieShould produce the same page for each overload except that parameters that do not apply are left out.

I do not know why you will prefer that to simply adding <inheridoc/> to each overloads.
The compilation time it will take to achieve that is hardly worth the effort. A quick start is to look at the Sandcastle
configuration file, you will see the point where the comments are copied into the build template (it is well commented).
The copying is done with copy component (class name CopyComponent, an implementation of which does the
inheridoc copy for you). See this...

http://sandcastle.codeplex.com/SourceControl/changeset/view/54478#397170

On the link to the overload page, it is unresolved issue because of the C# compiler bug introduced in 2005.
Using a syntax like <see cref="O:Namespace.Class.Method"/> will pass through without any compiler warning,
you can then either modify the sandcastle transformation or write a custom component to correct it before the link
resolver picks it (or rework the link resolver). See the following thread for further information on the transformation...

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

Best regards,
Paul. 

Editor
Apr 12, 2011 at 8:13 PM
Edited Apr 12, 2011 at 8:16 PM

I replied to your message in the SHFB forum regarding these issues in this thread: http://shfb.codeplex.com/discussions/59382

The thread noted above also contains links to possible changes to get <see> overload references working but they may have had issues as I recall and were for older versions of Sandcastle so I'm not sure if they'll still work.

Eric

 

Apr 13, 2011 at 3:30 PM

I got sharing to work like this:

/// <inheritdoc cref="LaunchShuttle(Uri, DateTime)"/>
public void LaunchShuttle(Uri destination, TimeSpan countDown) { }
/// <inheritdoc cref="LaunchShuttle(Uri, DateTime)"/>
public void LaunchShuttle(Uri destination) { }

Under SHFB, each documentation page, luckily, does select the correct subset of <param> tags to display, although the compiler will complain with CS1572 about parameters not present in the current overload. I guess Sandcastle can't do anything about that.

Regarding the difficulty linking to an overload list, I got it to work with a script I posted in this thread. Like previous solutions, my solution requires a fully qualified name like <see cref="O:Complete.Namespace.ClassName.MethodName"/>, but on the plus side it doesn't require modifications to Sandcastle itself. If I were a script monkey I could probably make it work the way I want, but I'm not, so that script alone took me hours on Google to develop.

@SelormeyPaul, I'm not sure why you even ask why I don't want to type out these inheritdoc tags manually. Repetitive mechanical work should be the computer's job. Also, inheritdoc is not in the VS autocompletion list, and some of my parameter lists are long and I don't enjoy typing them out.

As for the icons, there is no icon for repeated base-class members, and the icon for protected members is only subtly different from public members. IMO, a change to the entire row (and the sort order) would make it easier for users to find what they're looking for. So these presentation styles... where can I find them?

Editor
Apr 13, 2011 at 7:27 PM

You can find the presentation style folders in the \Program Files (x86)\Sandcastle\Presentation folder.  Under each one is a set of subfolders containing the scripts, stylesheets, resources, XSL transformations, etc.  The Prototype and Hana styles have been deprecated so you only really need to look at the VS2005 style files.  If you want to pursue changing the row color and sort order, you'll most likely have to add a style to the stylesheet and update one or more of the XSL transformations to use it in the right places and adjust the sort in the same places in the transformations.

Eric

 

Apr 13, 2011 at 10:54 PM

>>qwertie: /// <inheritdoc cref="LaunchShuttle(Uri, DateTime)"/>
Unless launchTime and countDown are the same, the above is why I opposed the support of even the inheritdoc.

>>qwertie: Repetitive mechanical work should be the computer's job.
I think VS supports macros and add-ins for a reason :)

>>qwertie:  ...but I'm not, so that script alone took me hours on Google to develop.
Planning to add a support to my build library as part of fixing the comments before the documentations to save time.

Best regards,
Paul. 

Apr 14, 2011 at 4:18 PM

>> Unless launchTime and countDown are the same, the above is why I opposed the support of even the inheritdoc.

So you thought it was better that users copy-paste the same documentation manually to each overload? Here's a thought... if the user provides documentation for only the first overload, why not put all overloads on a single page with that documentation instead of having separate pages for each one? Different overloads usually do the same thing, just expressing equivalent inputs in different ways, or have fewer parameters (the only way to "support" default parameters before C# 4). Am I the only one that thinks documenting each one independently is a waste of programmer time (and space in the help file)?

>> I think VS supports macros and add-ins for a reason :)

Are you suggesting each user should separately write their own VS macro or add-in that can figure out which overload has documentation and add <inheritdoc> to the other overloads? Even if more than 1 in 20 developers knew how, don't forget, we don't all have VS Professional Edition.

Apr 14, 2011 at 10:46 PM

>>qwertieSo you thought it was better that users copy-paste the same documentation manually to each overload?

Inherit what is common, (in this case the summary, remarks, parameter:destination), and then provide the difference.
In reality, each overloaded method does something special; providing default value for "missing" parameters for instance,
and there is no way this can be automated. The countDown in your sample could mean there is a startTime; may be the
time of calling the LaunchShuttle or there is a delay time after calling the LaunchShuttle. So the point is do you really
want to provide the user with a useful documentation or anything goes?

>>qwertie: Am I the only one that thinks documenting each one independently is a waste of programmer time...

That you do not want to use even the inheritdoc, as in your first post is what look strange. 

>>qwertie: Are you suggesting each user should separately write their own VS macro or add-in...

No, since personally I do not see the need for this, and it is not like every method in a every class is overloaded.
Adding inheritdoc is not a work I will wish to automate.
The point here is, the commenting part of the documentation process is done in the VS, and this is where you
automate if needed.  

>>qwertieEven if more than 1 in 20 developers knew how, don't forget, we don't all have VS Professional Edition.

Is not like a facility is not provided. And already, VS adds the template if you type ///, and you never have to type
a parameter list as you claimed in your earlier post.  

Only the Express edition meant for hobbyists and students does not support macros and addins.

There is more work still needed in the Sandcastle, that is why in my first post, I still went ahead and showed you
where to start, if you think this is a useful feature that deserves time and resources, then please contribute this to
the community.

Best regards,
Paul.