Moving XML comments to a separate file

Question

I love XML comments. However, with everything collapsed, every two lines looks like:

[/// summary ...]
public void CreateUser(string username, string password)[...]

Multiply this by tens or hundreds of methods, and the resulting collapsed code is hard to sift through. Can I move these comments to a separate XML file, and still have Visual Studio recognize the association so that they still show up in the Intellisense? If so, how do I make that association? And I'm also using SandCastle to generate documentation based on these comments, so the association will have to be recognized by SandCastle as well.

score 6 · Accepted Answer · answered Jul 18 '12 at 03:43

6

You can use the <include file='...' path='...'> tag to refer to external comments. See http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx.

I do not know of any tool that will move the comments in existing source file to an external comment file.

answered Jul 18 '12 at 03:43

Richard Schneider

34,944
9
57
73

score 3 · Answer 2 · answered Sep 18 '19 at 13:21

I'm probably 7 years late but I wanted to do the same and I found a way to get all the documentation in one XML but you may have to do the rest manually, add to the .csproj file the following:

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

And when you build your project, you're going to find in the output directory a <ProjectName>.xml file which will contain all your inline docs, you can copy the content of this file (You may have to edit some tags in the xml but probably not much) and place them in a file in your project.

Then you can replace the existing docs with the <include> tag.

score 0 · Answer 3 · answered Jul 18 '12 at 03:05

The short answer: AFAIK No.

XML comments are useful for publicly exposed methods that will be used by third parties. Since nearly all public facing functionality I add to applications is done through contract interfaces, (aids in test-ability) I'll put the comments against the interface declaration and just use a <see cref="..."/> above the implementation.

Interface:

///<summary>
/// Provides so-in-so fetching functionality on the provided criteria.
/// Examples, parameters, etc.
///</summary>
IEnumarable<Something> FetchSomethingsBaseOnCriteria(params Criteria[] criteria);

Implementation

///<summary>
/// <see cref="ISomethingDoer.FetchSomethingsBasedOnCriteria"/>
///</summary>
IEnumarable<Something> ISomethingDoer.FetchSomethingsBaseOnCriteria(params Criteria[] criteria)
{
  // Get fetching...
}

Not sure if most document generators have the smarts to resolve comments from the <see/> I believe Sandcastle has the <Inheritdoc/> tag which will allow it to take the base interface's comments. http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

Where you use polymorphic interfaces this may not work. (I don't think you can override declarations/comments in an intermediary interface)

For internal-use and private code I don't bother with comments as it's extra overhead often explaining the obvious. They're too easy to let fall out of sync in which case they start misleading users or need to be ignored. ("Comments lie." - Clean Code) I rely on BDD-styled unit tests to describe what I intend code to do, and descriptive code to describe itself.

Moving XML comments to a separate file

3 Answers3