-
Notifications
You must be signed in to change notification settings - Fork 683
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.
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
Initial documentation for doc comment references #6080
base: main
Are you sure you want to change the base?
Changes from 3 commits
2acef88
75d38b5
9a48173
5ff3658
2c3c897
56f7299
2e87da2
ea456a4
677de9e
478d7c7
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,82 @@ | ||||||
--- | ||||||
title: Documentation comment references | ||||||
short-title: Comment references | ||||||
description: Learn about doc comment references and their syntax. | ||||||
--- | ||||||
|
||||||
Doc comments can contain references to various code elements. A library member | ||||||
or class member, etc. can be referenced by wrapping its name in square brackets | ||||||
srawlins marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
(`[...]`) in a doc comment (a comment starting with `///`). Examples: | ||||||
parlough marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
```dart | ||||||
/// Returns a [String]. | ||||||
String f() => 'Hello'; | ||||||
|
||||||
/// Wraps [object] with [Future.value]. | ||||||
Future<T> g<T>(T object) => Future.value(object); | ||||||
``` | ||||||
|
||||||
These doc comments contain references to the `String` class, the `object` | ||||||
parameter, and the `Future.value` constructor. | ||||||
|
||||||
## Features of references | ||||||
|
||||||
There are several benefits to referring to a code element in a doc comment as a | ||||||
doc comment reference: | ||||||
srawlins marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
### Editor features | ||||||
srawlins marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
Doc comment references enable several IDE features. When an element is renamed | ||||||
via an IDE command, it can rewrite uses of that element, including references | ||||||
in doc comments. When an IDE lists all "references" to an element, it can | ||||||
include references in doc comments. An IDE can also provide Go-to-definition | ||||||
support at the location of a doc comment reference. | ||||||
parlough marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
### API documentation | ||||||
|
||||||
In API documentation generated by `dart doc`, a doc comment reference is | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can you cross link |
||||||
linked, if possible, to the documentation page of the element being referenced. | ||||||
If the element does not have a documentation page (for example, a function | ||||||
parameter, a type variable, or a private class), then no link is created. | ||||||
|
||||||
## What can be referenced | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think this section is useful but it's a bit long and will potentially be skipped over. Could we perhaps add another (complementary) section with a quick-reference table or list? I'm happy to help experiment with some options for doing so if you think it'd be helpful. I imagine it related each type of member with an example of its doc comment reference syntax. Many can likely be grouped together as well. |
||||||
|
||||||
Most library members can be referenced in a doc comment, including classes, | ||||||
constants, enums, named extensions, extension types, functions, mixins, and | ||||||
type aliases. This includes all in-scope library members, either declared | ||||||
locally, or imported. Library members which are imported with an import prefix | ||||||
srawlins marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
can be referenced with the prefix. Examples: | ||||||
srawlins marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
```dart | ||||||
import 'dart:math' as math; | ||||||
|
||||||
/// [List] is in scope. | ||||||
/// So is [math.max]. | ||||||
int x = 7; | ||||||
``` | ||||||
|
||||||
Most members of a class, an enum, an extension, an extension type, and a mixin | ||||||
can also be referenced. A reference to a member that is not in scope must be | ||||||
qualified with its container's name. For example the `wait` static method on | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We don't use the word "qualified" a lot in the docs. I think readers will mostly understand from the following context, but would it be helpful to clarify it means prefixed in this case?
Suggested change
|
||||||
the `Future` class can be referenced in a doc comment with `[Future.wait]`. | ||||||
This is true for instance members as well; the `add` method and the `length` | ||||||
property on the `List` class can be referenced with `[List.add]` and | ||||||
`[List.length]`. In-scope members like these can even be referenced without the | ||||||
qualifying container name: | ||||||
srawlins marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
```dart | ||||||
abstract class MyList<E> implements List<E> { | ||||||
/// Refer to [add] and [contains], which is declared on [Iterable]. | ||||||
void myMethod() {} | ||||||
} | ||||||
``` | ||||||
|
||||||
The doc comment for a function can include references to the function's | ||||||
parameters. | ||||||
parlough marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
The doc comment for a class, enum, extension, extension type, method, mixin, | ||||||
top-level function, and type alias can include references to its type | ||||||
parameters. | ||||||
|
||||||
The doc comment for a type alias cannot reference any of the aliased type's | ||||||
members, if it has any, as if they were in scope. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Describing doc comment references as referring to "elements" makes sense to me and I believe is what we've always said, but is that because of its implementation ties to the analyzer and our familiarity with it? I'm not necessarily saying we shouldn't use the term, but I just want to make sure it's the best term to use.
I can find very few cases in user-facing docs where we use the term "element" like this. Never do we say "code element". In fact, we are careful to use the term as it already has a few meanings (elements in a collection, collection literal elements, HTML elements, etc).
As a side note,
comment_references
lint docs use "in-scope identifiers".@bwilkerson for your thoughts, particularly based on writing diagnostic messages.
\cc @eernstg For your insight :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll stick to "identifiers" instead of "code elements" for now. Good call. I think "element" might be more correct in other cases. For example, an identifier is not referred to, a class is, via it's identifier. It is messy though.