new methods/demark erase methods ...

Mar 6, 2010 at 8:50 AM


I have 2 questions.

1,This is main problem. I want by to mark new methods, classis, etc some character (example "*"), my idea is find some variable (that is actual version) and then call over which methods, classis, etc. and after then add in topic character "*". Simpliciter i want demark new methods with other methods.

2, Some methods are not comments, then i see in HELP concrete method and nothing description (as summary, remarks) it is good. But when is description method in version 2.0 erased, and in Version managment are both version (1.0 and 2.0), then i see this method but i dont see any summary or remarks, and so i dont know this method is erased previously version or dont have fill tags summary or remarks. (Exist obsolete attribut, but sometimes somebody can by mistake and dont use this attribut)

Thank you for your help and sorry for my english.


Mar 12, 2010 at 12:57 AM

>> 1. This is main problem. I want by to mark new methods, classis, etc some character (example "*")

This is a missing feature in Sandcastle and in MSDN. You open that big documentation and you will not see
new methods and properties marked as such.

Currently, you can add this by using custom components. The way to do this is to tag your new methods/properties
with <new/> tag, and handle this in your custom component.

>> 2....

I am really sorry, I do not understand this question. You may try in your native language, may be someone can help translate.

Best regards,

Mar 12, 2010 at 3:06 AM


#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.

- Dave

Mar 12, 2010 at 4:12 AM

Hello Dave,

Thanks for the clarifications.

Best regards,