Update AV2305: Document all public, protected and internal types and members

[dennisdoomen]

This PR updates guideline AV2305.

It was split out of #298 so the change can be reviewed independently.

Files:

• _rules/2305.md

Part of the replacement for #298.

[bkoelman]

Are you sure about that? DocFX certainly doesn't pick them up when emitted. There's an additional pitfall to watch out for; the following is wrong:

/// <summary>A worker</summary>
public interface IWorker;
/// <inheritdoc/>
public class Worker: IWorker;

Instead, it needs to be:

/// <inheritdoc cref="IWorker"/>
public class Worker: IWorker;

Without the cref, you'll get the documentation for System.Object on Worker.

[dennisdoomen]

I've never reused documentation from the interface itself on the implementing types. I've only done this for members. And yes, even if you omit that tag, both Rider and R# will display the right documentation...

[bkoelman]

Interesting, I didn't know about that. Vanilla VS behaves the same. I know that Roslyn provides richer information when the source is available (in the same solution), so I tried referencing an assembly (with an .xml file next to it, but not a .pdb), and even then, it works for docs on members. But once <GenerateDocumentationFile>True</GenerateDocumentationFile> is added to the project file, it still emits CS1591 warnings.

But apparently, the warnings are by design:

That inheritdoc behavior is purely an IDE-time thing to help with features like quick-info. It's not a feature of the language, and docs are not inherited as far as the compiler and the rules around doc files are concerned. So the compiler is working as intended here.

Also, it doesn't work on types at all.

What API documentation generator is used by FluentAssertions, and does that also show docs on members from the interface without using <inheritdoc/>?

[dennisdoomen]

I never inherit type-level documentation from an interface or base-class. I always write something new as the type is different and usually has a different purpose.

[bkoelman]

It's less common, I suppose in depends on the kind of project. For example, a public library with well-documented interfaces for extensibility plus internal default implementations.

[bkoelman]

Here's an example:

// lots of docs, describing lifetime, constraints, which errors to raise, etc.
public interface IRepository<T>;

/// <inheritdoc cref="IRepository{T}"/>
internal class ArticleRepository : IRepository<Article>;

Can you answer the following?

What API documentation generator is used by FluentAssertions, and does that also show docs on members from the interface without using <inheritdoc/>?

[dennisdoomen]

Here's an example:

// lots of docs, describing lifetime, constraints, which errors to raise, etc.
public interface IRepository;

///
internal class ArticleRepository : IRepository

;

Even in this example, I really don't see the value of inheriting the documentation from the interface. In this particular case, most of the code only has to deal with the interface and never see the implementation. And for the folks that need to maintain the implementation, they can read the docs from the interface to understand how their implementation should behave.

What API documentation generator is used by FluentAssertions, and does that also show docs on members from the interface without using ?

What generator are you talking about? The .xml files are generated by the dotnet build CLI.

[bkoelman]

For example, this page: https://xceed.com/documentation/xceed-fluent-assertions-for-net/FluentAssertions~FluentAssertions.Primitives.GuidAssertions.html. Which tool renders the XML files?

[dennisdoomen]

I have no clue what they use for that. I'm not involved in that process. I can ask if it is really important

[bkoelman]

Oh, right. Well, it looks pretty much like docfx with a custom style template, so it likely won't pick up docs from base members if inheritdoc is omitted.

[bkoelman]

This used to be a solid rule, but now it has become subjective. It depends on how each developer feels about when something is helpful, and making it optional means that some developers will never add them. This defeats the goal of a universal style in the codebase, regardless of who implements it.

The accompanying analyzer flags when internal members are not documented (the other types are already covered by other tools). How is the analyzer supposed to handle the changed rule?

[dennisdoomen]

You're suggesting to remove the note completely?

[bkoelman]

I don't have a strong opinion on what should be documented on internal members, but I think the rule should be deterministic. Some options:

• Don't document internal types/members at all
• Internal types/members require at least a summary
• Internal types/members need to be fully documented (summary, type parameters, parameters, and return value)

[bkoelman]

For internal types and members that are only used within a single assembly

This implies that when using InternalsVisibleTo (for example, for tests), internal types and members must be fully documented. Is that desired?

[dennisdoomen]

I don't have a strong opinion on what should be documented on internal members, but I think the rule should be > deterministic. Some options:

Don't document internal types/members at all
Internal types/members require at least a summary
Internal types/members need to be fully documented (summary, type parameters, parameters, and return value)

This is a problem for me. I want people to document everything, but only if it adds value. I don't want to be dogmatic about it. Repeating the name of the method in a single-line doc is a waste of effort. And quite often I don't even bother documenting some parameters or return values. E.g. nobody needs to understand what a CancellationToken is or what the purpose is of the returned Task.

[dennisdoomen]

Well, in that case, we remove that note as the consensus seems to be to also document internal types and members. A tech lead or architect can always reduce the level of that rule to suggestion

[dennisdoomen]

Agreed?

[bkoelman]

I'd like to better understand the tooling impact first, before providing suggestions. As soon as GenerateDocumentationFile is turned on, something must appear to silence compiler warnings: empty summaries or inheritdocs. This enables tracking missing places to document while making it easy and explicit to not document certain places where it doesn't add value. Undocumented new code triggers a warning.

For teams that don't produce a docs website or aren't too serious about documenting, they would typically leave GenerateDocumentationFile off, be fine with a partially documented codebase (and not being alerted when new code isn't documented at all), and rely on the unofficial in-IDE expansions for inheritdocs.

The rule seems to have been created for the former scenario, not the latter.

[dennisdoomen]

I'm a bit lost on what you're trying to achieve. In terms of documentation, it is subjective. I don't think we can make this rule deterministic as it depends on the member involved. If I have to document it myself, I decide on a case-by-case basis, and if I'm using an AI Agent, it is usually more rigid on this.

[bkoelman]

Two concerns:

1. Whether a type/member needs to be documented is subjective. Don't state the obvious. I agree with that.
2. How does that deterministically work in the C# compiler? By turning on GenerateDocumentationFile and silencing the resulting warnings with either documentation, an empty summary, or inheritdoc.

If this rule didn't mention internal, then no custom analyzer would be needed. Its only purpose is to behave the same as the built-in C# warning for internal types and members. That's how it behaves today, and it works well. Neither requires adding returns and parameter documentation. If desired, there are StyleCop analyzers to enforce that.

So we can make this rule deterministic if you're willing to accept adding empty summaries or inheritdoc as the way to express that no documentation is needed. I still believe that works best.

Therefore, my proposal would be:

• Revert all changes to this PR
• Addition: Turn on GenerateDocumentationFile to track places to potentially document
• Addition: Don't state the obvious; use an empty summary or inheritdoc instead (with example)
• Extra tip (rare cases perhaps): use cref in inheritdoc for interfaces, otherwise it points to System.Object

Regarding the example:
Prefer:

/// <summary />
public void StartWorker(TimeSpan timeout);

Instead of:

/// <summary>Starts the worker.</summary>
/// <param name="timeout">The timeout.</param>
public void StartWorker(TimeSpan timeout);

[Copilot]

Pull request overview

Updates guideline AV2305 to better explain the value of functional documentation, and adds guidance/exceptions around when to document members.

Changes:

• Rewords the introductory explanation for documenting types/members.
• Adds a “See also” cross-reference to AV2306.
• Adds an exception for obvious/repetitive documentation and a note about <inheritdoc/>.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.