Neither does the analyzer. Please let us know if you decide to accept this syntax so that we can keep in sync.

Is there any linking for ctors at the moment?

Is there precedent (in other doc tools) for [new Class.ctor]?

I think the proposal is fine...just want some context

cc @alan-knight.
cc @efortuna.

For what it's worth, here's the grammar that used to be in the language specification (but has since been removed) and that analyzer still uses:

commentReference ::=
    '[' 'new'? qualified ']' libraryReference?

libraryReference ::=
     '(' stringLiteral ')'

I don't know how often the "new" is included. Analyzer will resolve the reference to the constructor either with or without it.

Can one have name collisions between the name of a ctor and static/instance members?

Is using the 'new' prefix just for clarity in the source code or does it enable a new feature?

Can one have name collisions between the name of a ctor and static/instance members?

Not in error-free code. According to the specification:

A constructor name always begins with the name of its immediately enclosing class, and may optionally be followed by a dot and an identifier id. It is a compile-time error if id is the name of a member declared in the immediately enclosing class.

Is using the 'new' prefix just for clarity in the source code or does it enable a new feature?

In analyzer, it doesn't change anything. We know because of the class name that we're referencing a constructor, so the 'new' has no effect. As far as I know, it's merely a question of personal taste.

I guess referring to the default ctor vs the class is one feature.

This comment was originally written by @seaneagan

Yes, and presumably the same syntax should be used to refer to constructors in docs as for closurizing them in code, which is issue #10659.

To answer your question, Kevin, Dartdoc can and does link to constructors currently. You need to link it like [Foo.Foo] for the basic unnamed constructor to distinguish it from the classname itself, though.

Removed Pkg-DartDoc label.
Added Pkg-DocGen label.

It's not clear to me whether "Foo.Foo" is a valid constructor name (votes are 2:1 for from the implementations). If so, [Foo.Foo] should refer to that, and not to [new Foo].

It's not clear to me whether "Foo.Foo" is a valid constructor name ...

Section 7 of the specification (Classes) states:

  It is a compile time error if a class C declares a member with the same name as C.

I think this precludes the use of the class name as the name of a constructor. (I think it's a bug that analyzer doesn't currently catch this case.)

But personally, I think it's ugly to use [Foo.Foo] to refer to the default constructor of a class because it doesn't match the syntax of the language. I agree that [new Foo] is not great either, but I do think it's better.

cc @gbracha.

Sadly, Foo.Foo is a valid constructor name per spec. Given that some implementations accept it, I don't see that we should change the spec.

Foo.Foo is a valid constructor name per spec.

Then I won't create an issue against analyzer for this case :-)

But I think that means that it isn't safe to use "Foo.Foo" for the unnamed constructor, and we really do need to support "new Foo".

okay dogen will need to be changed.

Moved to dart-lang/dartdoc#103

Added MovedToGithub label.