Remove rules about DartDoc comments in the language specification

[eernstg]

Update: This PR removes everything in the language specification that is concerned with documentation comments. The treatment of this topic area is now fully determined by each tool team.

---

Previous description:

The language specification specifies the syntax that makes a comment a DartDoc comment, which is unchanged. This PR adds a paragraph of 'rationale' text explaining that everything else is tool specific behavior, and it removes the rules about scoping in DartDoc comments.

There were no rules about the locations where a DartDoc comment can occur, which means that it is still "any location where a comment can occur". Moreover, each tool can freely choose that a DartDoc comment is processed in a specific way when it occurs in a specific kind of location (including that it is ignored, or a diagnostic message is emitted).

[sigurdm]

I wonder if it would be useful to specify which element a given documentation comment associates with.

I get the language team prefers to not decide everything here. But we need something for the teams to work with.
I propose that we somehow piggy-back on the specification on annotations: any place that can have an annotation can be preceded by a dartdoc comment that will then associate with that element.

[eernstg]

specify which element a given documentation comment associates with

We could say that any given DartDoc comment is associated with a syntactic element of kind <someNonTerminal> if it immediately precedes the leftmost token in the derivation from that non-terminal that yields the given program (ignoring whitespace, other comments, and metadata).

This might very well associate any given DartDoc comment with several distinct syntactic elements (because they all start with the same token), but there is no ambiguity unless the DartDoc comment is meaningful for more than one of those syntactic elements (all the others will just "ignore" that DartDoc comment).

However, all these decisions could also be made by the relevant tool team(s), which was the motivation for the change as proposed in this PR. Is it important to standardize explicitly on these things?

[sigurdm]

However, all these decisions could also be made by the relevant tool team(s), which was the motivation for the change as proposed in this PR. Is it important to standardize explicitly on these things?

If we expect users to use a feature, and multiple tools need to work with it, it needs to be specified/standardized. It doesn't have to be by the language spec per se, but I wonder where is a better place to spec this out...

[eernstg]

The language team decided that we should have the syntax of the DartDoc comment in the language specification, but nothing about where it can occur and how it is determined which syntactic construct it is targeting. Now I hear requests for keeping more stuff in the language specification, and less. For now, I'll just keep the text as decided at that meeting. ;-)

[bwilkerson]

If we expect users to use a feature, and multiple tools need to work with it, it needs to be specified/standardized. It doesn't have to be by the language spec per se, but I wonder where is a better place to spec this out...

I agree, all of our tools need to support doc comments in the same way. The two tools that I know of that interpret doc comments are the analysis server and dart doc. All of the support for the analysis server is in the analyzer package, and most of the support for dart doc is too. There is a longstanding desire to move the remaining dart doc support into the analyzer package, because sharing code is the best way I know of to maintain consistency.

I have no objection to having a written specification of the behavior somewhere, and we minimally need to have user-facing documentation so that users know how to use the feature effectively.

I would recommend that we move this conversation off to a separate thread and make sure that the conversation involves all of the right participants (minimally the pub team, since they now own dart doc, the dart model team, who owns the analyzer package, and the developer experience team, who owns the analysis server).

[eernstg]

@bwilkerson, I created #4513 in order to discuss the desired level of specification. This PR will lay dormant until #4513 yields a decision.

[eernstg]

The newest commit removed everything in the language specification about documentation comments, which seems to be the approach that has general support.