Skip to content

Remove rules about DartDoc comments in the language specification #4511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 10, 2025
+7 −28
Merged

Remove rules about DartDoc comments in the language specification #4511

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b12cf1c
Remove the rules about DartDoc comments in the language specification
eernstg Sep 4, 2025
88aa40e
Remove everything about documentation comments from the language spec…
eernstg Sep 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 7 additions & 28 deletions specification/dartLangSpec.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@
% version of the language which will actually be specified by the next stable
% release of this document.
%
% Sep 2025
% - Remove the rules about DartDoc comments. This topic is now handled by each
% of the tools that process those comments in any way.
%
% Jul 2025
% - Clarify that operator `[]` and `[]=` are included in the `void` allowlist
% rule about formal parameters of type `void`, and so are setters.
Expand Down Expand Up @@ -23406,40 +23410,15 @@ \subsubsection{Comments}
Dart supports both single-line and multi-line comments.
A \Index{single line comment} begins with the token \code{//}.
Everything between \code{//} and the end of line
must be ignored by the Dart compiler
unless the comment is a documentation comment.
must be ignored by the Dart compiler.

\LMHash{}%
A \Index{multi-line comment} begins with the token \code{/*}
and ends with the token \code{*/}.
Everything between \code{/}* and \code{*}/
must be ignored by the Dart compiler
unless the comment is a documentation comment.
Everything between \code{/*} and \code{*/}
must be ignored by the Dart compiler.
Comments may nest.

\LMHash{}%
\IndexCustom{Documentation comments}{documentation comments}
are comments that begin with the tokens \code{///} or \code{/**}.
Documentation comments are intended to be processed by
a tool that produces human readable documentation.

\LMHash{}%
The current scope for a documentation comment immediately preceding
the declaration of a class $C$ is the
\IndexCustom{body scope}{scope!for statement body}
of $C$.

\LMHash{}%
The current scope for a documentation comment immediately preceding
the declaration of a non-redirecting generative constructor $k$
with initializing formals is the formal parameter initializer scope of $k$
(\ref{generativeConstructors}).

\LMHash{}%
Otherwise, the current scope for a documentation comment immediately preceding
the declaration of a function $f$ is the formal parameter scope of $f$
(\ref{formalParameters}).


\subsection{Operator Precedence}
\LMLabel{operatorPrecedence}
Expand Down