Can C# files contain file-level summary comments?

Question

E.g.

Foo.cs:

using System;

/// <summary>
/// This file contains Foo and Bar-related things.
/// </summary>

namespace Xyz {


class FooThing {
}

}

Does C# support such XMLDoc comments?

Answer 1

No, XML document comments can only appear on specific types of elements, as described in this article:

In source code files, documentation comments that precede the following can be processed and added to the XML file:

Such user-defined types as a class, delegate, or interface

Such members as a field, event, property, or method

If you place a file-level XMLDoc-style comment in your file, it will be appended to the next class or other element that happens to appear. Certain documentation tools, like Sandcastle, provide a way to add namespace-level XMLDoc comments but they generally appear in a separate file.

Of course, you can use non XMLDoc-style comments in each file, e.g. a copyright header or similar, by just using standard /* */ style comment blocks.

Answer 2

According to the /doc documentation, no, that is not supported.

In source code files, documentation comments that precede the following can be processed and added to the XML file:

• Such user-defined types as a class, delegate, or interface

• Such members as a field, event, property, or method