Linter: Erroneous "Prefer using /// for doc comments. dart(slash_for_doc_comments)"

[toddabel]

Dark SDK:
Dart VM version: 2.3.0-dev.0.5.flutter-a1668566e5 (Tue Apr 30 20:35:41 2019 +0200) on "windows_x64"
Flutter 1.5.4-hotfix.2 • channel stable • https://github.com/flutter/flutter.git
Framework • revision 7a4c33425d (8 weeks ago) • 2019-04-29 11:05:24 -0700
Engine • revision 52c7a1e849
Tools • Dart 2.3.0 (build 2.3.0-dev.0.5 a1668566e5)
Editor: VSCode 1.35.1

When including a file header and statements such as below without an import statement, the Dart analyzer emits "Prefer using /// for doc comments. dart(slash_for_doc_comments)" information statement, but when an import statement is added, the statement goes away.

/***************
* Copyright Blah, blah
* File: Blah
* Created: Blah
****************/
// import 'dart:async';
class Foo {}

[lrhn]

(This looks like a linter issue, so I'll move it to the linter repo).

If there is no import statement, then the copyright comment is a doc-comment on the class.

If you introduce an import, then the comment becomes a doc-comment on the import.
Because nobody cares about comments on imports, it's likely considered a doc-comment on the library, which should otherwise be on the omitted library declaration.

Not sure why doc-comments on libraries/imports are not giving the warning, though. Seems like they should, the documentation (https://dart-lang.github.io/linter/lints/slash_for_doc_comments.html) doesn't mention exceptions.

The workaround would be to write the comment as a non-doc comment:

// Copyright Blah, blah
// File: Blah
// Created: Blah

or

/* ************************************
 * Copyright Blah, blah
 * File: Blah
 * Created: Blah
 **************************************/

(notice the space, so the comment doesn't start with /**).

[toddabel]

Obviously not a big issue as there are lots of work arounds as you mention. It does seem that headers should be allowed, maybe an exception for comments that start at line 1? I can create an issue in VSCode also as this is their standard header for Dart.

[bwilkerson]

... maybe an exception for comments that start at line 1?

Most top-level declarations, and the comments that go with them, start in column 1, so that doesn't seem like a viable option.

I can create an issue in VSCode also as this is their standard header for Dart.

Yes, please. The file header should not be a documentation comment. It should be a block of end-of line comments, similar to

// Copyright Blah, blah
// File: Blah
// Created: Blah