#2: I was emailed this question directly but it seems that I have misunderstood it as well. I think it's clearer to me now though:
When you remove APIs from your assemblies, the version management tool will still produce documentation for them with a note that it was only available in a previous version. However, the XML documentation is no longer available for these
older APIs because they're no longer part of the original codebase being compiled, which is where the XML documentation file comes from that is fed to Sandcastle. So you end up having older methods in your documentation without any comments. (And
you don't want to use the older XML documentation files because they may contain old documentation for existing APIs.)
One possible solution is to not remove APIs and instead use ObsoleteAttribute, but as the OP pointed out, this may not be ideal because you have to remember to add this attribute and then you must hope that devs honor it.
Another solution is to manually or programmatically compare the old XML documentation file with the new XML documentation file to look for APIs that no longer exist in the new XML documentation file. Once you have identified the missing documentation,
there are two options:
A. Insert the missing XML documentation elements into the new XML documentation file and Sandcastle will pick it up automatically.
B. Remove the common XML documentation elements from the old XML documentation file and ensure that Sandcastle can see both of them.
How to do either of these depends upon which automation tool that you're using, if any. But generally you can write a simple add-in or command-line executable that collects the set of unique API names from each XML document, performs a simple
comparison on those names, and isolates all of the "missing" elements. Then you can choose to implement option A or B. Finally, register your add-in with the automation tool at an early phase in the build process.