Comment references to unnamed constructors do not match Dart code

[jamesderlin]

A specific case for #1663: The Effective Dart guidelines claim:

The dot syntax can also be used to refer to named constructors. For the unnamed constructor, put parentheses after the class name:

/// To create a point, call [Point()] or use [Point.polar()] to ...

I just tested this with dartdoc 0.24.1 from the Dart 2.1 SDK, and the unnamed constructor reference doesn't seem to work; it links to the class instead.

https://github.com/dart-lang/dartdoc/wiki/dartdoc-comment-references instead says to use [MyClass.MyClass] to reference the unnamed constructor. That does work, but the generated documentation literally has MyClass.MyClass, which looks weird since that's not what anybody uses in code. Can we do one (or both) of:

• Make [MyClass()] refer to the unnamed constructor as claimed by Effective Dart? (Or, less desirably, fix the false claim by Effective Dart.)
• Make [MyClass.MyClass] show up as MyClass (or MyClass()) in the generated documentation?

?

The motivation for this was my attempt at removing lingering new usage in Flutter API documentation, which was used to disambiguate references to classes from references to constructors (flutter/flutter#24625).

[jcollins-g]

The first bullet point seems reasonable, although I don't know if there are existing references looking like that that are intended to refer to the class documentation. Dartdoc strips extraneous things like "new " and "()" because it is considered rare to refer to the unnamed constructor. Usually, the class documentation is what people seem to want.

If the () notation is not widely used to refer to the class docs, then we can implement this.

[jcollins-g]

adding @kwalrath, given the report that the () does not work as advertised on Effective Dart.

[Hixie]

We definitely want to be able to refer to constructors (including unnamed one, which we sometimes refer to e.g. from named ones, or from properties, to say "hey look at the guidance on the argument to the constructor", etc). I admit I never tested whether that worked...

[jcollins-g]

@Hixie You can do so now (and it is done this way in parts of the docs) with [ClassName.ClassName] for the unnamed constructor and [ClassName.fooConstructor] for others. The problem as I understand it is that it isn't very darty (noone calls constructors like that) and doesn't match what we're told to do in Effective Dart.

[jamesderlin]

The documentation for the comment_references lint also claims that [Class()] should work:

In particular, code references within square brackets can consist of either
...

• a single identifier followed by a pair of parentheses where the identifier is the name of a class that is in scope (used to refer to the unnamed constructor for the class), or

[srawlins]

With constructor tearoffs, the new canonical way to reference an unnamed constructor is with .new: /// [List.new].

[jamesderlin]

https://github.com/dart-lang/dartdoc/wiki/dartdoc-comment-references hasn't been updated and still refers to MyClass.MyClass. Since it's part of the dartdoc wiki, I don't think I can create a pull request to change it (and I'm guessing that I can't or shouldn't push changes directly to the wiki repo).

[jamesderlin]

I just tried this again (using dart 2.16.2), and all of the following now do generate references to the unnamed constructor:

• [Foo.new]
• [Foo.new()]
• [Foo()]
• [Foo.Foo]
• [Foo.Foo()]

And in all cases, the string within the square brackets is shown verbatim in the generated documentation.