Build Comment Web Pages

In VS2003, there is a feature known as “Build Comment Web Pages” that was designed to take XML doc comments from your code, and create web page documentation.

If you try to find it in VS2003, you won’t have much luck, and I thought I’d explain why. We got a fair amount of customer feedback around the disadvantages of the current implementation, and that it wasn’t really very useful.

We’ve therefore elected to pull it from Whidbey. We are exploring whether we can provide a feature that meets our customers needs in the future, but it didn’t fit into the schedule.

Luckily, NDoc is available, and it comes much closer to what you want than Build Comment Web Pages did. You can find articles about it here and here and here and here. Oh, and here, too.

Comments (14)

  1. Eric Wilson says:

    I think you meant that you tried to find in VS2005

  2. Art says:

    Actually, i just found that yesterday in docs, while trying to figure out how to make intellisense work. I think it’s nice.

    By the way, if you know how docs work… My problem is with <summary> etc. part of comments. It does show up in intellisense (in second line of yellow box) if i type in same project, but if i have multiple projects they don’t share those comments, only syntax. Do you know what’s wrong?

  3. J. Daniel Smith says:

    I don’t like the XML comments because you have to name things like argument names/types twice. Once in the actual C# code, and then again in the XML for documentation.

    While XML comments are a small step in the right direction, something more like Knuth’s literate programming is needed.

    And of course, comments can be a crutch for writing poor code; clearly written code can minimize the need for a lot of commentary.

  4. Art, this will answer your problem:

    "To use the generated .xml file for use with the IntelliSense feature, let the file name of the .xml file be the same as the assembly you want to support and then make sure the .xml file is in the same directory as the assembly. Thus, when the assembly is referenced in the Visual Studio project, the .xml file is found as well." You can find more info here:

  5. Adam Byram says:

    I’ve got to say that I really liked this feature. Now I agree that the Build Comment Pages function didn’t really do anything useful (and I have been using NDoc ever since I found out what it was) BUT, I really like the XML comment system. Especially when you just hit /// and it automatically fills in everything for you about the function other than the description. This stuff really helps to get other people up to speed on a function…anyway, I hope the xml comment features in the editor will remain even without the actual build comment web page function.

  6. Chad Myers says:

    Eric, I hope you still read this, it’s pretty far down the list of blog entries….

    I feel the need to point out that there is a really good group of tools out there for all the secondary development tasks (automating build, building documentation, unit testing, etc) in the NAnt/NDoc/NUnit2 collection. NUnit2 is a little rough, but it’s getting better. NAnt and NDoc are amazingly rock-solid and full featured.

    What I, as a daily .NET developer, would like to see, if VS.NET play better in this world. Rather than MS trying to reinvent the build, documentation and/or unit test world, allow these tools to more easily integrate into VS.NET. I think MS should stick to writing amazing kick-butt IDE’s, compilers, runtime environments, etc and support the community in developing these tools because they can do it faster, cheaper, and crank out more features or at least more custom-tailored features than MS can. This is specially the case when you consider that .NET 2.0 is at least 12 months away, if not 18 or more.

    Please stop trying to reinvent the wheel and focus on more features in ASP.NET, core framework, windows forms, etc. Leave the secondary tasks to the community. The .NET community is exploding right now and it’s a Very Good Thing(tm), please don’t squash that (not that you’re trying, but you may accidentally).

  7. MBA says:

    Helpful For MBA Fans.

  8. Documentation Tools

    The essence of documentation can never be under-estimated in software.&amp;nbsp; Be…