Allow doc comments to use formal parameter initializer scope

[parlough]

Since initializing formals are not added to the formal parameter scope, doc comments can't access them. If the initializing formal parameter scope exists, doc comments should be allowed to use them. That way constructors can reference super parameters.

I've never adjusted the spec before, so please review closely :) - For example, with this exception, is it not clear what the scope for other constructors is supposed be? Should the function one expand its text?

\cc @eernstg

[eernstg]

Thanks, this looks good! However, I've suggested a few changes.

This is mostly in order to follow the pretty-much-unwritten rules of the language specification (like: "which occurrences of a phrase will give rise to an index entry?" or "where do we put line breaks in LaTeX source?"), but also one thing that affects the meaning directly: We should have a link between the generative constructor case and the "otherwise" case. I've suggested putting the narrowest case first and then covering everything else by starting the next paragraph with 'Otherwise'.

[parlough]

Thanks for the feedback @eernstg, I applied your suggestions! Starting with the narrowest case makes a lot of sense, I didn't consider that :)

One final question: In terms of the spec, is the otherwise case stating "function" sufficient for also covering constructors not covered in the special case?

[eernstg]

LGTM, thanks!

The word 'function' does cover constructors:

language/specification/dartLangSpec.tex

Line 1944 in 0ecd65a

and constructor declarations (\ref{constructors});

.

[parlough]

The word 'function' does cover constructors:

Makes sense. Thanks for confirming :)

@eernstg Feel free to land if you're happy with this change. I don't have commit access on this repository. Thanks again!

[eernstg]

OK, thanks! Landing.