XML Doc comments and include files…

When we first added XML doc comments to C#, we thought that using them would give
us much more accurate documentation, as the developers would update the docs when
they changed the code. This works pretty well for small libraries, but if you have
a UE group that works on your docs, it’s pretty inconvenient for them to have to check
out your source files to work on docs.

So, we added an “include” syntax that lets you keep the docs in a separate file, which
the compiler then reads to get the actual xml to use.

This is all documented here

Comments (8)

  1. Eric,

    This is great, but I think that you haven’t looked at this feature from the enterprise perspective. Perhaps I am wrong in thinking this, but I would think that I would want to see things like author and revision history as well in the XML documentation, but the current schema doesn’t support any of that. This makes it very difficult to unify this information into one place.

    – Nick

  2. Dan Smith says:

    Since you mentioned XML doc comments… :-)

    IMHO, the system doesn’t really solve the UTSL ("use the source, Luke") problem. What if I alter the argument list in some way? I’ve got to update the XML comments to match. It would be A LOT nicer if I could list the arguments one time in one place and be able to write the documentation at the same time. Knuth got a bit closer to this in [C]WEB.

    Taking this one step further, the native file-on-disk format could be XML. The first thing a compiler does is run this XML through a XSLT transform to generate source code. Of course, Visual Studio.NET hides this XML from you, you see source code just as you do today (but through a different XSLT transform). Of course, in practice, you might not really use XSLT transforms for performance reasons…

  3. Eric says:


    I don’t understand your comment about "the current schema". The compiler doesn’t impose any schema – all it cares about is that the xml is well formed.

  4. Daniel O'Connell says:

    I’ve wanted to use this a few times, just for small libraries even, but a few problems:
    One problem I have with this is that, in VS.NET, using the include tag requires an explicit pathname, because VS.NET, atleast at times, executes the csc compiler in its bin folder instead of in the project directory. You end up with complaints about the xml file location and no docs. It should work fine with a tool like Nant, but I am not always doing the major piece of building with such a tool.
    Another is the inability to view that documentation IN the editor. Sometimes reading the xml comments of a method I’m not highly familiar with or a manual rundown to ensure that I didn’t accidentally leave a param tag in is of value. It would be nice if the source editor was capable of handling the <include> tag and directly importing that xml into a collapsable comment region, preferably with the ability to edit inline, but that feature would not be nessecery.

  5. I am glad you brought this up :) Can you describe in more detail how the MS teams use the include files. Does the developer create the include file? When does the UE team edit the content? Also, using the include you loose the ‘///’ fill functionality.

    What would be nice is to create a form to edit the content of the file in a tool window. as the developer moves into a function the form shows the current xmlDoc for that function in a nice format. The toolwindow would either insert the summary info inline or insert an include directive based on the project settings.

    IMHO, The XmlDocs is great but it has a long way to go before it can be useful in a team environment. I for one think this should be a very high priority item to improve in Whidbey.

  6. Pete Vidler says:

    Hmm.. I see this as useful for duplicate parts of comments, such as examples that should be included in several places. I much prefer the main comments (summary, remarks and param) to be in the actual file.

    Dan: If the native file-on-disk format were XML, I and a lot of others who don’t use VS would desert .net for Java or C++. Anyone that thinks XML is a good, human readable format deserves to be shot — it’s far too hard to see the content for the tags.

  7. John Lewicki says:

    Im late to the party here, but I just want to add that I find it extremely annoying that the IDE no longer picks up the documentation when an include file is used; I really wish that could be corrected…