proposal: `library_with_comments_or_annotations`

[kevmoo]

library_with_comments_or_annotations

Description

Doc comments and/or annotations that are meant to be "scoped" to a library should be attached to a library; directive and not just "floating".

Details

We have a bunch of silly rules trying to deal with doc comments and annotations "floating" that are meant to be scoped to a library (and not the first import/export directive).

Preferring these to be connected to a library directive would make their purpose clear and likely help formatting and code analysis tools.

Kind

style

Good Examples

/// This is a cool library doc comment
@WithAnAnnotation()
library; // assuming https://github.com/dart-lang/language/issues/1073 lands with support for no-name library directives

import 'dart:async';

Bad Examples

/// This is a bad floating library doc comment
@WithAFloatingAnnotation()

import 'dart:async';

Discussion

This is the ONE case where https://github.com/dart-lang/linter/issues/3686 (prefer avoiding library directives) would not apply!

Adding no-name libraries proposal: dart-lang/language#1073

This could likely be added to Effective Dart, I think.

Discussion checklist

• List any existing rules this proposal modifies, complements, overlaps or conflicts with.
• List any relevant issues (reported here, the SDK Tracker, or elsewhere).
• If there's any prior art (e.g., in other linters), please add references here.
• If this proposal corresponds to Effective Dart or Flutter Style Guide advice, please call it out. (If there isn’t any corresponding advice, should there be?)
• If this proposal is motivated by real-world examples, please provide as many details as you can. Demonstrating potential impact is especially valuable.

[srawlins]

The annotation bit might be tricky; it might be intentional. But the doc comment case I think is unambiguous.

[srawlins]

Perhaps if we only complain about annotations on the first directive (like an import), our false negatives will be extremely minimal. And then not worry about annotations on the first member (like main or something).

[kevmoo]

Perhaps if we only complain about annotations on the first directive (like an import), our false negatives will be extremely minimal. And then not worry about annotations on the first member (like main or something).

Or (likely more difficult) lint when they are "floating" – with newlines below them.

[bwilkerson]

We could also flag for annotations whose target kind is 'library' because that's an unambiguous signal.

[kevmoo]

FYI: the associated language feature has LANDED for Dart 1.19!

[kevmoo]

Dropped prefer_ prefix as is tradition

[srawlins]

Sorry I missed this request. These are each complete now, with the library_annotations and dangling_library_doc_comments lint rules.