dart-lang / dart-lang/language

Unable to write doc comment or metadata on primary constructor

Open
#3,300 7 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.