Write documentation for linking to non-trivial dart entities

[lrhn]

It's not documented anywhere how to link to non-trivial Dart entities.

Simple [prefix.class.member] references, or relative [nameInScope] are easy (which scope is used should be documented, though), but it's not clear how to link to:

• Unnamed constructors: [C] refers to the class, the constructor has no other name.
• Operators: [==] or [operator ==]? [unary-]? In another class it's [C.==] or [C.operator==]? [[]] or [operator[]] or ?
• Setters: [foo=]?

Can you refer to a parameter of a function? [foo.paramName]? (You can refer to it with a relative name in the doc for the function itself, so it's not clear whether you can refer to it from the outside).

Can you refer to a library (if inside it and using its name? If outside it?)

(I've been writing Dart libraries for years, and I can't answer these questions, so please help me) :)

[jcollins-g]

@lhrn I want to write a design doc to define this before implementing https://github.com/dart-lang/dartdoc/issues/1402#issuecomment-301517026, which is likely to change how all this works pretty dramatically. What we currently do has many exceptions and corner cases where it doesn't work (including #1402, #1285, and more that people just haven't found yet). Still, it's a real bug that this isn't documented.

[jcollins-g]

I'll add that the fact that case by case I still have to experiment to tell someone what will and won't work is a symptom of the general problem of dartdoc's old, buggy table-based implementation being the specification here.

[jcollins-g]

An incomplete document that we can expand on: https://github.com/dart-lang/dartdoc/wiki/dartdoc-comment-references

[jcollins-g]

Underlying this is that comment references in dartdoc are an unspecified language defined by dartdoc's implementation; we can do better here and as the implementation becomes more consistent I'll try to make this more of a priority.