Should the language specification standardize DartDoc comments? How much?

[eernstg]

The language team recently discussed making changes to the language specification material about DartDoc comments (it's just a few paragraphs near the end of the subsection about comments).

It currently specifies the syntax of a DartDoc comment and the scope that references to names in a given DartDoc comment should be resolved in when it occurs immediately before certain kinds of declarations.

The PR #4511 was created in order to remove the scoping related rules, based on the realization that the list of situations is shorter than the set of locations where DartDoc comments may be useful to have, and it seemed more productive to leave these decisions to tool teams, rather than repeatedly adding new locations to the language specification when needed.

For example, nothing was said about formal parameter declarations, and they are very likely to need to have DartDoc comments in the future when declaring constructors (including primary constructors) are added to the language.

This issue is intended to clarify the following question: How much should the language specification specify (and hence standardize) about DartDoc comments? Some models come to mind:

• Nothing. A comment is a comment according to the language, and tools can do whatever they want.
• The syntax (/// and /** at first will turn a comment into a DartDoc comment). Nothing is specified about where they can occur or how anything in there will be interpreted or processed. This as what Remove rules about DartDoc comments in the language specification #4511 will do, if landed without radical changes.
• The syntax, and in special cases the scoping (this is what we have today). It should then be mentioned explicitly in the language specification that other locations may also have DartDoc comments, and their scoping is simply the current scope of the location where it occurs, such that the language specification rules on this topic only need to be extended when another tricky-scope case emerges (if ever).
• (It is not likely that anyone will recommend that even more specification is added about DartDoc comments in the language specification, so we stop here).

So what do you think?

@bwilkerson, could you add a comment below, and notify the people you had in mind to consult in order to clarify this matter properly?

[bwilkerson]

The first option listed above is acceptable to me.

The second option is also acceptable to me, even though it isn't clear to me that we need to say anything in the specification about a distinction that only the tools are making.

I can see an argument for having it in the spec so that there's one central place where all special-case uses of comments is listed. (I'm guessing that the spec says, or will say, something about the language override comments. It seems like that really should be in the spec rather than in some extra-spec document.) But that argument assumes that we want to have all that information in the spec, and it isn't clear that we do. (If we do, we might want to add ignore comments to the list for completeness sake.)

If we don't want to have all that information in the spec, then I think it would be fine to have it elsewhere, even if it means duplicating some of the information about the language override comments.

The third option seems bad to me. I wouldn't want part of the definition to be in the specification and part of it elsewhere because it will be too hard to keep it all consistent. And I don't think we want to have to update the language spec every time the tools need to update the way doc comments are handled. (Which also negates the fourth option.)

As for the people that need to be involved, I think that's

• @jonasfj and @sigurdm for the pub team
• @johnniwinther, @scheglov, and @stereotype441 for the dart model team
• me and @srawlins for the developer experience team

If I've missed anyone they'll probably know.

[lrhn]

(The language specification does not mention the // @dart=3.7 comments because the language specification is specifying one langauge version. The tools then implement multiple language specifications and allow the user to choose between them. Language versioning is an extra-linguistic tooling feature, the language itself - every version if it - acts as if it's the only language there is. That might be too simplistic, but it's the model.)

[bwilkerson]

Good to know, thanks.

In that case I think there's no reason for the spec to say anything about special-case comment handling, and I'd vote for option 1. But I'm still fine with option 2 if that's the majority opinion.

[parlough]

From a documentation perspective, I think 1 is fine. Developers' expectations and writing practices for doc comments come from dart.dev (mostly Effective Dart currently) and support from the analysis server, not the language specification. Before I opened dart-lang/sdk#54307, I didn't even imagine or know the scoping was documented in the spec.

We already document doc comments, such as doc comment references, in the context of tooling rather than the language (it's even in a /tools directory instead of /language). As we expand and update the docs, we can continue to just document the behavior implemented by the analyzer (and dart doc by extension).

[johnniwinther]

cc @szakarias for DartDoc

[szakarias]

To me, the cleanest approach is to exclude documentation comment specification entirely from the core language specification. From the language perspective they are simply comments.

The responsibility for parsing and interpreting doc comments should belong to the tooling (like dart doc and the analysis server) as these tools determine how that information is best presented to the user. A specification for doc comments is very relevant, but it should exist and be maintained separately from the core language spec.

[eernstg]

Very good! The PR in #4511 now removes everything about documentation comments from the language specification.

[mateusfccp]

Should this be closed?