HowTo: Managing partial C# method order in help document

Topics: Developer Forum, User Forum
Dec 3, 2012 at 3:29 PM

I have C# classes that are partial. I am having a problem that the xml summaries for the classes are not being built into the documentation in the same order every time. Sometimes the designer class is first, sometimes my parial classes summary is first. Is there a way to make all classes deterministic? Can I force the order of parial class inclusion into the build process to get the order I want in to output help document?

Coordinator
Dec 3, 2012 at 4:49 PM

More likely than not, the order of the designer class comments and your partial class comments is at the mercy of the compiler as I'm assuming they end up in a single XML comments file after your assembly is built.  In such a case, it will depend on how the compiler outputs the merged comments.

If it leaves both summary elements in the resulting comments file, you could probably introduce a custom sortOrder attribute to your summary elements.  You could then write a plug-in for SHFB that would scan the XML comments for members with summaries with a sortOrder attribute and order the summary elements.  For example, assume zero for those missing a sortOrder attribute such as those in the designer class and use a negative or positive non-zero number on your partial class comments summary elements to sort them into the right place.

If the compiler merges the summary elements into a single element, you may be out of luck.  One possible solution in that case would be to wrap your comments in a custom element.  Your plug-in could then search for that custom element, pull it out, and reposition its content in the summary comments accordingly.  The other alternative is to manage the affected member comments in a standalone XML comments file and have a plug-in remove them from the compiler generated XML comments file so that your external comments file takes their place.

Eric

 

Dec 3, 2012 at 9:30 PM

Thanks Eric.

While all those suggustions are well worth considering, I found that in this case my simplest solution was to move all the xml document comments into one of the partial classes. Of cource, it's the one that I maintain not the generated ones.

I will have to consider using one of your methods however for the poco classes generated from entity framework tt templates. There is no other way I see to get the xml document comments into the file before I build them with sandcastle help file builder.

Thanks again.