dart-lang / dart-lang/language
Unable to write doc comment or metadata on primary constructor
- Dominant language
- TeX
- Stars
- 2.9k
- Forks
- 239
- Avg merge
- 2d 18h
- Merged PRs (30d)
- 14
Description
I believe that neither the [spec for extension types](https://github.com/dart-lang/language/blob/main/accepted/future-releases/extension-types/feature-specification.md) nor the [proposed spec for primary constructors](https://github.com/dart-lang/language/pull/3023) allow for doc comments or metadata (annotations) on a primary constructor.
Maybe that's fine. Let's examine each of these cases:
#### Cannot specify doc comment on an extension type's primary constructor
Well, an extension type's primary constructor can only have one parameter. The meaning of that parameter is always the same. Maybe it is difficult to conceive of a case where a doc comment specific to the primary constructor is important.
If the ability to specify doc comments is important, maybe we can just introduce a [doc comment directive](https://github.com/dart-lang/dartdoc/wiki/Doc-comment-directives), e.g.
```dart
/// An extension type.
///
/// {@primary-constructor}
/// Wraps an [int] as a [V1].
/// {@end-primary-constructor}
extension type V1(int it) {
```
(Doc comment directives use kebab case; it is important to use as many cases in a programming language as possible.)
#### Cannot specify metadata on an extension type's primary constructor
This one worries me because I have to imagine there are plenty of cases where users desire to annotate a constructor. Maybe many cases can be handled by just assuming an annotation on the extension type is intended for the primary constructor. Maybe not.
I want to highlight the 3 primary purposes of annotations:
* trigger static analysis, like `@visibleForTesting`, `@experimental`, etc.
* trigger/inform code generation. I'd like to look at what code generation systems might use metadata on constructors, especially built_value, json_serializable, freezed.
* (future) trigger macro execution. The possibilities are pretty open wide here. CC @jakemac53
#### Cannot specify doc comment on a (class's, etc.) primary constructor
Move the constructor (and fields) to be written explicitly, and then document the constructor as usual. The same goes for documenting the fields.
#### Cannot specify metadata on a (class's, etc.) primary constructor
Move the constructor (and fields) to be written explicitly, and then annotate as usual.
Contributor guide
Research direction
Start with the linked extension-types feature specification and proposed primary constructors specification. Compare their treatment of doc comments and metadata on primary constructors, including the extension-type and class cases, then document a resolved language-design direction and update the relevant specification text.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- dart
- Domain
- compilers
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100