Documentation is not generated for private top-level getters and setters

[sgrekhov]

According to the specification, doc comments can be placed before top-level getters and setters, and there is no exception for getters and setters with private names. However, doc comments are currently not generated for top-level getters and setters with private names.

I’ll add a link to the appropriate tests after the PR containing those tests lands.

Dart SDK version: 3.12.0-49.0.dev (dev) (Tue Jan 20 08:02:46 2026 -0800) on "windows_x64".

[srawlins]

This is all correct. I don't believe there is any issue here.

HTML documentation is not generated for private elements. They are still useful when parsed in IDE environments, and for other static systems, like code search, and bulk fixes.

[sgrekhov]

Specification doesn't make an exception for private named getters and setters. Documentation is generated for top-level class-like declarations, typedefs, functions and variables with private names. It is not generated for private top-level getters and setters only (I didn't test class members yet). If this is intended, then, please, update the specification accodingly.

[srawlins]

The Dart Documentation Comments specification is a specification for doc comments themselves, not a specification for what the dartdoc tool will spit out, or how it will spit things out (for example, should a class member be documented on the class's page, if it is 100% inherited? What if the comment is inherited, but the impl is not? What if it is 50% inherited, like a getter overriding a mutable field?)

The specification notes:

Its goal is to ensure that documentation is parsed consistently by all tools and to serve as a definitive standard for developers and tool authors.

This again is just about parsing, not rendering.

This document does not cover:

• The implementation details of specific documentation tools (e.g., dartdoc, analysis server).
• Any details related to the visual styling or HTML layout of generated documentation.

@szakarias it might be good to be explicit about how this doc does not cover what is output by any given tool; sort of a generalization of the "implementation details" bullet above.

[szakarias]

I agree with @srawlins. The spec defines the syntax, placement, and resolution of documentation comments. It does not mandate how or if a specific tool renders that documentation.

Whether dartdoc chooses to generate HTML for private members is a tool-specific policy, not a violation of the comment specification itself.

I will update the specification to explicitly state that output decisions (like visibility filtering) are out of scope.

[szakarias]

#4189

[sgrekhov]

OK, thank you. With a new understanding of the spec, this is not an error. According to the specification, tools must ignore doc comments that are placed in locations where they are not allowed, but they are also free to ignore them in places where they are allowed.

But wouldn’t it be more consistent if dartdoc, by default, generated documentation for private getters and setters? It already generates documentation for private variables and constants, and (at least for me) it’s surprising that it doesn’t do the same for getters and setters.

[szakarias]

Could you perhaps clarify? I'm not seeing dartdoc generate HTML for any private members, including top-level variables and constants. Am I missing something, or could you provide an example?

[sgrekhov]

Please see https://github.com/dart-lang/dartdoc/pull/4188/changes. In the tests in this PR documentation is generated for all private top-level members except getters and setters.

[srawlins]

The documentation fields referenced there are not the HTML output. They are processed Markdown comment text.

So this is the comment text with delimiters (///, /**, etc) stripped. And then directives processed like {@youtube} and {@tool}. And macros injected, so {@macro} replaced by the corresponding {@template} text.

If some private elements have a non-null documentation field, and others have a null documentation field, that's no bug that I can think of, unless we see consequences in the generated HTML.