1

Is there a tool that can just extract my XML comments in a code base and put them in an XML file? I don't want to maintain a seperate file myself, I want to generate the XML when I am done and remove the content from the source code.

Improve this question
3
  • 4
    Why would you want to do that? It then forces maintenance programmers to have to look at the comments in the other file AND in Visual Studio. Personally, I LIKE having comments in with the code. Right there next to the function/object/logic I'm deciphering. You don't really maintain it in two places by leaving it in code. You maintain it in code, and the rest gets automatically generated when you build. Commented Apr 18, 2012 at 21:23
  • @DavidStratton There may be a plugin that can display the comments on demand and sync them to another XML file. XML comments hurts my eyes while reading the code. Commented Apr 18, 2012 at 21:26
  • You could collapse the comments. Commented Apr 18, 2012 at 21:58

2 Answers 2

Reset to default
3

The problem with the approach you are asking for is that as soon as you change the code, your "precompiled xml" will drift out of sync with it (or if you want to stop this hapening, you will have to edit the xml file by hand, which will be a thousand times worse than seeing the original XML comments!). I think you really ought to consider embracing the doc comments and making the most of the many benefits (direct and indirect) that come from using them. But if you want to do it, you only have to enable generation of the XML doc output, rebuild the project, then copy out the XML files from your bin\debug or bin\release folder, and start slashing and burning.

There are other, less destructive options, however:

  • You can change the syntax colouring colours for documentation comments in Tools > Options : Environment > Fonts and Colors. Use a faint colour and the comments will fade into the background.

  • Perhaps if the comments were tidier, they wouldn't make your eyes bleed. I've written an addin (Atomineer Pro Documentation) that can apply a comprehensive range of formatting options to doc comments to make them more pleasant to look at: optional separators above/below comments, optional whitespace in and around entries, optional columnar alignment of the text blocks, optional word-wrapping, etc. Or if the XML tags are what really hurt, it can convert your comments to a less jarring format (it supports Doxygen, JavaDoc and Qt as well as XML documentation).

  • My addin also has an option that can use the "outlining" facility in VS to hide doc comments (on demand or whenever a document is opened). It might alleviate some of your symptoms by essentially hiding the doc comments.

  • Theoretically it's possible to write a VS2010 extension that can change the display of doc comments to remove the markup and show a more wysiwyg representation. I haven't heard of anything but there may be something out there now that will help you.

Improve this answer
Sign up to request clarification or add additional context in comments.

1 Comment

I'll take a look at your addin. Hiding comments may do it for now. I was thinking about a plugin that works on external XML files because then it would enable to inherit comments from base types, interfaces and some other fancy stuff. Of course editing comments is done on the source file and plugin should take care of the changes.
1

You can use Visual Studio compiler with /doc switch. This option is also available in project properties on Build tab and is named XML documentation file. It would generate separate XML file with comments which could then be used by IntelliSense. It is meant to be used if you were to distribute the compiled assembly with usage comments (utility library). There is also something called Sandcastle. Check this link

You might also have a look at NDoc. It will generate code documentation based on your XML comments. It's open source.

If you're looking more into how to make comments less distracting it is helpful to change their color to something more pale (Tools -> Options -> Environment -> Fonts and Colors). You can also use a macro to collapse all comments.

Anyway I do advice to leave comments in your code - it makes code a lot more maintainable.

Improve this answer

2 Comments

As far as I know NDoc isn't maintained anymore and it has troubles with .NET 4.0.
@UfukHacıoğulları You can also use VS itself to generate XML doc file. I have updated my answer and added other options as well.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.