Extension method documentation

Apr 8, 2009 at 1:15 PM
Hi all,

we are using extension methods heavily in our product. The .NET framework documentation includes these in the documentation for the interface/class members for the type of the this parameter in a separate section (see IEnumerable<T> for an example). However, this section is missing for our documentation (generated with current sandcastle and SHFB 1.7) - is there any way to make them appear for the extended types?

Regards
JM
Editor
Apr 8, 2009 at 3:59 PM
SHFB 1.8.0.1 contains the fix that documents the extension methods correctly.  You should also apply the latest Sandcastle Styles patch so that the Sandcastle transformations include the extension method language in the topics too.

Eric
Apr 9, 2009 at 4:27 PM
Edited Apr 9, 2009 at 4:30 PM
Well, it's still working only partially for some reason. I have applied the current sandcastle style patches as well as the fix in this work item: http://shfb.codeplex.com/WorkItem/View.aspx?WorkItemId=20291 (which doesn't seem to be a part of the styles patchset yet?). Also, I've switched to SHFB 1.8.0.1, which seems to contain the necessary mrefbuilder.config update. DocumentAttributes is also set to true. I'm using the most recent Sandcastle version. Now I actually get the "extension usage" for the actual method documentation, but the "Extension Methods" section is still missing.

I can't find any usages of the extensionMethodTable item defined in reference_content.xml anywhere either in Sandcastle or SHFB, which strikes me as odd - it looks like this part is missing completely?

If necessary, I can provide a small sample project - I guess I have to open an issue to do that?

Forgot to mention: I'm using the VS2005 style...
Editor
Apr 9, 2009 at 4:35 PM
The Sandcastle transformations don't currently generate a separate "Extension Methods" section and they'd need to be modified to produce it.  I hadn't noticed it before so didn't realize it was missing.  Regarding DocumentAttributes in SHFB, in can be left set to False in 1.8.0.1.  The extension method attribute is excluded from the attribute removal process.

Eric
Apr 14, 2009 at 10:05 AM
Thank you for your help,

I already suspected so :-/ Is this doable for someone with moderate XSLT but rather minimal Sandcastle knowledge? Which parts would I have to modify (so far, I've only added support for some custom tags, which could be done completely in the main_sandcastle stylesheet)? Or should I just wait for a fix - we require this functionality soon, but not immediately.

Regards
JM
Editor
Apr 14, 2009 at 8:28 PM
If you know XSL fairly well and can figure out which parts of the reflection file it needs to use, it should be possible.  You'd have to figure out which templates were responsible for generating the Methods and Members pages and modify the Method section in each so that it only lists non-extension methods and add a new section for extension methods if there are any.  You'd probably have to filter them based on the presence or lack of the ExtensionMethod attribute.

You can open a work item here to request that it be added.  You might also add a work item to the Sandcastle Styles project.  I don't have the time to implement it right now but might be able to later if someone else doesn't get to it first.

Eric
May 11, 2009 at 6:54 PM

Oh well... After a closer look at the MrefBuilder source code I noticed that there is already an ExtensionMethodAddIn available - just had to add

<addin type="Microsoft.Ddue.Tools.ExtensionMethodAddIn" assembly="Sandcastle\ProductionTools\MRefBuilder.exe" use-gac="false" />

to MrefBuilder.config et voilà...

 

Regards

JM