Basic .new support for constructors

[jcollins-g]

Continuing work on #2655.

This is a little squirrelly, since we allow referring to default constructors via old and new methods. Also, not working with typedefs yet.

[srawlins]

Hmm, I'm not sure I understand this. You cannot "declare" a default constructor. Does the analyzer create a synthetic one with the name, .new?

[srawlins]

Oh, analyzer's ConstructorElement has a isDefaultConstructor which returns true if the element can be used as a default constructor. It makes sense in a client API though, because generally subclasses do not care if the unnamed, zero-arg constructor of a super class is default or not; they only care whether it exists.

[jcollins-g]

It's a little difficult to parse through what is merely the analyzer's API for accessing it and what someone looking at the spec would say, and the lay programmer, for sure. I do intend "default constructor" to mean "thing that will be used by default to construct this object". There seem however to be three general cases:

1. No constructor is declared, e.g. class A {}. In this case, I am intending for the A.new name to be available to refer to the "unnamed" constructor, as well as A.A, an alias that already exists.

2. A constructor is declared as A.A(param1, param2). Dartdoc calls this a "default constructor", and an unnamed constructor, for historical reasons, because the name of it is indistinguishable from case 1 and back when this code was written there seemed to be no way to definitively disambiguate the two situations in all cases.

3. A constructor is declared as A.new(param1, ...). Dartdoc will also call this "default constructor", but no longer an unnamed constructor. Presumably it is illegal to have case 2 and case 3 at the same time, haven't actually checked :-)

[srawlins]

A constructor is declared as A.A(param1, param2).

Do you mean A(param1, param2)? Declaring a constructor as A.A() is not an unnamed constructor, and cannot be invoked via A().

A constructor is declared as A.new(param1, ...). Dartdoc will also call this "default constructor", but no longer an unnamed constructor.

Why no longer unnamed? If you declare a constructor with A.new(param1, ...), it is (according to the spec, and analyzer) an unnamed constructor, and can be invoked with A(...). Is this saying that a constructor declared with A.new(param1, ...) cannot be referred to in docs via [new A()]?

I'd actually be surprised that you could discover that one was declared with A.new because I think I ensured that the analyzer always considers that constructor as named '' (unnamed).

[jcollins-g]

TL;DR is that dartdoc has been wrong about how default constructors work, but not in a way that has actually caused any real world problems and probably would continue to have been oblivious were it not for tearoffs. I'll try to rationalize this now.