New Idea for XmlComments

Now that the InfoPath team has release the new SDK, I am inspired to do something new. I love the fact that we have XmlComments in C# and that it has the support including comments from external files. This makes it easier to separate the comments so that the doc people can work on them without affecting your code.  The problems right now are:
1. There is no way for a dev to put in the comments and then externalize them (rip them out and put into a file with the correct tags)
2. There is no editor for the comments

My idea is to solve both these problems with InfoPath as an editor, and an extension to VS for the ripping. If anyone has any ideas or knows of existing projects out there that can help, I would love to hear from you. I plan to start working on this over the next month and then post something to GotDotNet. 

Comments (3)

  1. SergioL says:

    Check out DocumentX from Innovasys at It has a really intuitive editor.

  2. Jeff Parker says:

    You know, I got to spend a day with 4 people from the VSFT and this one one thing I get saying. I Agree with you the XML Comments and Documentation is great. This is a fabulous feature with C#. But Like you said there is no real tools for working with the comments. Typically what I do is I type them up in Front Page 2003 since it is HTML and XML Compliant already and has Spell Check and grammar check then copy and paste into my code. Now Why I do this in this way is something to keep in mind.

    End Result, first think of where your end result needs to be. To make a viable help file for your code you want it to end up either being html or chm So everything needs to be portable into Microsofts HTML Help, or Help Workshop. I say both because it seems MS started down the HTML Help path but then abandoned it. So it left the more powerful tools in the Help Workshop. Anyway to use this you eventually got to get everythign into HTML. Anyway what would be nice is some of this integration into VS but I use NDoc open source on sourceforge to turn the XML Comments into HTML then import into Help Workshop to do any additional html I need. The Help Workshop will also take full front page webs and generate help structure and search indexes and stuff for you so it is a pretty cool little tool. Then it compiles it into chm.

    Anyway writing help from your code I see as a big area for improvement. the addition of XML comments is great but now getting from XML to chm and html with good quality has still a lot of room for growth. But I am not discounting your Idea, I just think Front Page and Help Workshop would be a better places for this, how would be interesting in seeing what kind of ideas you have been mulling around.

  3. bspkal says:

    I’m not sure if this is what you had in mind but…

    Compile your code with the /doc switch (or by defining a xml output file in your project properties/configuration properties/build/XML Documentation File). This will give you an XML file with all the XML comments and their respective tags.

    As for the editor, if you are talking about commenting as they are coding, you

    can use a third-party tool like Whole Tomato’s Visual Assist. This program

    allows you to create templates or use their autotext feature that can place the

    XML tags in the code when needed, and the developer then only needs to modify

    the comments within.