Add dart documentation comment specification version 1.0.0 #4130
Conversation
szakarias
force-pushed
the
commentspec
branch
from
70470e8 to
dbac532
Compare
|
The questions below are mainly questions about future versions of this spec.
/// Some doc comment about class C
class C {
/// Some doc comments about the constructor
C([int p]);
}
/// Another doc comment about class C
augment class C {
/// Comment about the constructor
augment C([int p = 0]) {
// Augmentation added the defaulf value and the body
}
}
/// Some doc comment. Is it related to the class or to the constructor?
class C(var int x); |
|
|
||
| ### **2.3. Content Format (Markdown)** | ||
|
|
||
| The text within a documentation comment block is parsed as Markdown, allowing for rich text formatting. This includes headings, lists, code blocks, and emphasis, which are converted for instance to HTML in the generated documentation. |
There was a problem hiding this comment.
It's probably worth mentioning that they are parsed as CommonMark markdown, as "markdown" is not a well-specified syntax.
There was a problem hiding this comment.
(For the record, "MarkDown" is also specified, https://daringfireball.net/projects/markdown/, it's just that nobody actually uses that specification. That's why CommonMark was created.)
There was a problem hiding this comment.
Ah you're correct. It is GitHub-flavored Markdown, an extension of CommonMark.
| * **Display:** The getter and setter should be presented as a single item in the final documentation. | ||
| * **Precedence:** | ||
| * Documentation for the property should only be placed on the getter. | ||
| * The tooling should *issue a warning* if both a getter and its corresponding setter have unique doc comments. |
There was a problem hiding this comment.
How does inheritance factor in here?
If I override a documented field with a setter, can I document the setter?
If a supertype has a documented setter, and an undocumented getter, and I override the getter, can I document the overriding getter (thus making both the getter and setter documented)?
|
|
||
| Documentation tools should handle this property with the following rules: | ||
|
|
||
| * **Display:** The getter and setter should be presented as a single item in the final documentation. |
There was a problem hiding this comment.
I disagree. The hover should know that it is a setter, but display the singular documentation for the property, and that documentation should cover both is read and write aspect. This would also avoid having documentation that isn't shown; if you painstakingly write documentation on the setter it would be unfortunate that is only shown when you hover and not elsewhere.
As a side note, DAS is a bit inconsistent with this. For instance if you ask for usage on a setter, you still get all the results that read the property, indicating that it is using the conceptual property in this case.
|
|
||
| * **Doc Comment:** A comment intended to be processed by documentation generation tools, like dartdoc. | ||
| * **Element**: A specific, declared element in the Dart code, such as a class, method, function, variable, or type parameter. | ||
| * **Identifier:** An individual name in the code (e.g., `MyClass`, myMethod, prefix). |
There was a problem hiding this comment.
Code-quote myMethod too, probably also prefix.
|
|
||
| * The *syntax* for writing documentation comments. | ||
| * The rules governing where documentation comments can be *placed*. | ||
| * The mechanism for *resolving* references between elements. |
There was a problem hiding this comment.
It is covered in the terminology section, now with updated definition. I guess I could swap 1.2 and 1.3. It feels a bit backwards to define terms before explaining what the doc is about.
| ### **1.3. Terminology** | ||
|
|
||
| * **Doc Comment:** A comment intended to be processed by documentation generation tools, like dartdoc. | ||
| * **Element**: A specific, declared element in the Dart code, such as a class, method, function, variable, or type parameter. |
There was a problem hiding this comment.
(Cyclic definition: An element is a (specific declared) element. Then some examples, but one has to guess what they have in common.
The concept of "element" is an implementation detail in our tools, it's not a term that the language specification uses. It's not a word we can assume a reader will understand by themselves, so if we want to use it here, it needs to be defined, non-circularly. Or just use "declaration" or maybe "named declaration".)
There was a problem hiding this comment.
Good catch, I would like to keep element for this doc. Updated the definition.
| ### **4.4. Local Scope Parameters (within a member's doc comment):** | ||
|
|
||
| * Parameters of the documented method/function (e.g., `[parameterName]`) | ||
| * Type parameters of the documented element (e.g., `[T]`) |
There was a problem hiding this comment.
And type parameters of surrounding declaration.
class ValueHolder<T> {
final T value;
ValueHolder(this.value);
/// Converts a [T] to an [R] using [function].
R callWith<R>(R Function(T) function) => function(value);
}
|
|
||
| * Parameters of the documented method/function (e.g., `[parameterName]`) | ||
| * Type parameters of the documented element (e.g., `[T]`) | ||
|
|
There was a problem hiding this comment.
(Could this section simply say "any declaration whose name is in scope other than import prefixes"? Plus qualified names where the first identifier must denote "any declaration in scope".)
| | +----------------------------------------------------------------------+ | | ||
| | | 6. Imported Scopes (all 'import' directives + implicit 'dart:core') | | | ||
| | | +------------------------------------------------------------------+ | | | ||
| | | | 5. Library Scope (all other declarations in the file) | | | |
| | | | | | +------------------------------------------------------+ | | | | | | ||
| | | | | | | 2. Method Type Parameter Scope (e.g., <R>) | | | | | | | ||
| | | | | | | +--------------------------------------------------+ | | | | | | | ||
| | | | | | | | 1. Formal Parameter Scope (e.g., parameter names)| | | | | | | |
There was a problem hiding this comment.
(And for initializing constructors, use the initializer list scope instead, since that contains the names of initializing formals and super parameters too.)
|
|
||
| #### **5.3.1. Instance Methods and Constructors** | ||
|
|
||
| This applies to doc comments on methods, constructors, and operators within a class, enum, mixin, extension, or extension type. The search begins with the method's own parameters. |
There was a problem hiding this comment.
(But not setters. Maybe say that explicitly.
They have a parameter list too, but I can see that's inconsistent with treating them as properties. If I do:
class C {
void cake() {}
/// Is it [cake]?
set bar(int cake) {}
}it looks like DartDoc refuses to make [cake] a link. It probably resolves to the setter parameter, but there is no target for a setter parameter to link to. If that's the case, a setter doc does start at the parameter scope.
I guess that answers my "anything but import prefixes" question above in the negative. "Anything but import prefixes and setter parameters."?)
| class MyClass<T> { | ||
| T? value; | ||
|
|
||
| MyClass.named(); |
There was a problem hiding this comment.
(Consider:
/// A non-redirecting generative constructor.
///
/// Lookup examples:
/// * [value]: Resolves to the parameter.
/// * [other]: Resolves to the parameter.
/// * [MyClass.value]: Resolves to the instance variable.
/// ... (more?) ...
MyClass.value(this.value, int other);)
|
|
||
| ``` | ||
|
|
||
| #### **5.3.2. Instance Fields** |
|
|
||
| This applies to doc comments on fields within a class, enum, or mixin. Since fields have no parameters, the search starts at the member level, but otherwise follows the same route as instance methods. | ||
|
|
||
| * **Starting Scope**: Class Member Scope |
There was a problem hiding this comment.
(And getters and setters are treated like fields?)
|
|
||
| * **Starting Scope**: Library Scope | ||
|
|
||
| #### **5.3.5. Top-Level Declarations** |
There was a problem hiding this comment.
The two prior sections are also top-level declarations.
|
|
||
| #### **5.3.6. Typedefs** | ||
|
|
||
| The starting scope for a typedef doc comment depends on what it is an alias for. For function and record types, the scope starts at the parameter/field level. For all other types, it starts at the typedef's own type parameter scope. |
There was a problem hiding this comment.
(This may need to be accounted for in the definition of what an "element" is. Type aliases for structural types do not introduce any declarations, their field/parameter names are not what I would usually consider expect to be an "element".)
| *Case 1: Import Prefix* | ||
|
|
||
| * **Namespace:** The export scope of the imported library, as filtered by any show or hide combinators on the import directive. | ||
| * **Example:** In `[math.pi]`, the identifier `math` resolves to an import prefix (e.g., from `import dart:math' as math;`). The tool then searches the public namespace of dart:math for the identifier pi. |
There was a problem hiding this comment.
... searches the prefixed import namespace for the identifier pi.
If you have multiple imports with the same prefix and/or show/hide modifiers, the public namespace of the imported library isn't the whole truth.
|
|
||
| * **Notes on Generics:** | ||
| * The namespace does not include the element's own type parameters. For a class `MyClass<T>`, a reference like `[MyClass.T]` is invalid because T is not a member of `MyClass`'s namespace. | ||
| * References are also made to the generic declaration, not a specific instantiation (e.g., write `[List.filled]`, not `[List<int>.filled]`). |
There was a problem hiding this comment.
Or else?
Currently it seem like the type argument is ignored, but the linking works.
| * **Example:** To resolve the reference `[collection.BoolList.empty]`: | ||
| * The identifier collection resolves to an import prefix. | ||
| * The identifier BoolList resolves to a class element within the collection library's public namespace. | ||
| * The identifier empty resolves to a named constructor element within the BoolList class's member namespace. |
There was a problem hiding this comment.
Today List.List.empty also resolves to the List.empty constructor in the List namespace. (Which can be convenient?)
| * **Namespace:** The set of all members declared within that element, including: | ||
| * Instance Members (fields, methods, etc.) | ||
| * Static Members | ||
| * Constructors |
There was a problem hiding this comment.
Also type-aliases (typedef) probably works like the type they alias, if they alias a specific type.
|
Did I miss anything about actual HTTPS style links? That's been a problem w/ the analyzer lint for a while! |
9 participants
No description provided.