58 lines
1.6 KiB
Plaintext
58 lines
1.6 KiB
Plaintext
== Why is this an issue?
|
|
|
|
In Dart there's a possibility to write a documentation (doc) comment on the library. This will help the users of the library to get some general understanding what is the purpose of the library. The comment might contain some examples, library specific terminology, or anything else that you think might be relevant.
|
|
|
|
Such comments might accidentally become dangling if placed in the beginning of the file but without the `library` directive. It is important to make sure that comments are placed right before the `library` directive.
|
|
|
|
== How to fix it
|
|
Move the doc comment before the library directive.
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,dart,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
/// A really great test library.
|
|
|
|
import 'some_import';
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,dart,diff-id=1,diff-type=compliant]
|
|
----
|
|
/// A really great test library.
|
|
library;
|
|
|
|
import 'some_import';
|
|
----
|
|
|
|
== Resources
|
|
|
|
=== Documentation
|
|
|
|
* Dart Docs - https://dart.dev/tools/linter-rules/dangling_library_doc_comments[Dart Linter rule - dangling_library_doc_comments]
|
|
* Dart Docs - https://dart.dev/language/libraries#library-directive[Library directive]
|
|
* Dart Docs - https://dart.dev/effective-dart/documentation#consider-writing-a-library-level-doc-comment[Effective Dart]
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
* Dangling library doc comment.
|
|
|
|
=== Highlighting
|
|
|
|
The first line of a doc comment
|
|
|
|
'''
|
|
== Comments And Links
|
|
(visible only on this page)
|
|
|
|
endif::env-github,rspecator-view[]
|