Running intellisense component as postbuild step

Nov 11, 2013 at 1:31 PM
Hi

I want to fix the inheritdoc problem for intellisense as a postbuild step for every csproj. The postbuild step would modify the created xml documentation file and replace all inheritdoc tags with the original content. Is there a way to achieve this? I can't find a possibility to modify the original xml documentation file with the sandcastle help file builder.

Kind regards
Michael
Coordinator
Nov 11, 2013 at 5:18 PM
Edited Nov 11, 2013 at 5:21 PM
I wasn't aware that there was a problem with inheritdoc and IntelliSense. Care to elaborate?

Edit: Just saw your other post about code contracts. If this is related to that, adding the set of relevant code contracts elements to the IntelliSenseComponent used by BuildAssembler will take care of the issue.

Eric
Nov 12, 2013 at 7:11 AM
Hi Eric,

As described here
http://connect.microsoft.com/VisualStudio/feedback/details/783839/intellisense-doesnt-work-for-overridden-members-decorated-with-inheritdoc-tag
Intellisense uses the generated XML documentation to show information. That doesn't work for inheritdoc documentation. When building NuGet packages it is common to include the xml documentation so intellisense can show the help information for the external library.
So in general it would be great to have a post build step in every c# project that will fix the inheritdoc tag in the generated xml documentation. Running the whole shfb project would be to much overhead and I didn't find a setting to modify the original xml documentation. The IntelliSenseComponent just creates a copy.

Kind regards,
Michael
Coordinator
Nov 12, 2013 at 3:12 PM
The inherited documentation is generated by a separate tool (GenerateInheritedDocs.exe) It generates a new XML comments file containing the updated XML comments. You could probably run it and create a separate tool to merge those comments back into the original XML files or the GenerateInheritedDocs tool could be updated to merge them back in if ran in a standalone fashion outside of SHFB.

Eric
Nov 12, 2013 at 4:01 PM
Whats the command line argument for GenerateInheritedDocs.exe? Passing the generated XML file doesn't work.
Coordinator
Nov 12, 2013 at 4:42 PM
It requires the name of a configuration file as the one and only command line argument. See the one in source control for a description of the elements in the configuration: https://shfb.codeplex.com/SourceControl/latest#SHFB/Source/GenerateInheritedDocs/GenerateInheritedDocs.config

The easiest way to get one that works for you is to build your SHFB project and once it gets past the Generating Inherited Documentation step, cancel the build. You'll find the configuration file it used for the build in the working files folder.

I had forgotten that the tool is dependent on the reflection information file so MRefBuilder also needs to be ran to generate the reflection information file. A such, it's not as simple as just running GenerateInheritedDocs to produce the merged comments file. A better solution would be a plug-in for SHFB that runs enough of the build steps to generate the inherited documentation and then suppresses all subsequent build steps sort of like the Additional Content Only plug-in. The plug-in could then handle merging the comments and copying the resulting XML comments file(s) to the output folder.

Eric