I am creating a public API and recognize the value of the full API document on public methods. I know that it is easy to put them directly into code files as XML annotations on classes, methods, properties, etc.
But I hate to close clean source code with public comments. What is the best way to create XML code documentation elsewhere than code files, and still produces in Visual Studio , Which removes .xml from the appropriate location (\ bin \ folder, etc.)?
I personally have to be with the comments in the code. You can always keep the areas around you and tighten them. Keeping them directly with the code, you get the benefit of filling in Intelligence in parameter names and so on. I know that this may be a bit of a distraction, but I'm getting the best way to go this. It also means that while reading the code, you can check that you have documented it so easily.
To place an optional comment in a separate file (per file source) and pre-builder phase, files that were mixed in some temporary areas, from where you are created from there XML comments will need to be some identifier in front of them, to make it clear to which member they describe, and you have to type the device to merge. You can make this simple by adding a single comment before each method, for example
// doccomment: MyMethod (asd) The latter bit is irrelevant, only used as a token, but I'm sure you can come up with your own conference to sync with another file, which will look like this:
< Pre> // doccomment: MyMethod (asd) /// & lt; Summary & gt; /// This method started pressing the frobidizer. /// & lt; / Summary & gt; Then you can replace a line of comment with the text identified in the comment file.
It makes all sounds like a real burden - I guess it's long and difficult to see how painful the code comments really are.
Comments
Post a Comment