proposal: dartdoc comment references should more flexible

[bartekpacia]

Description

I've often felt restricted by comment_references lint when writing doc comments for more complicated code. I sometimes find myself wanting to reference

/// Does important stuff.
///
/// If [data.someProperty1.someProperty2] is null, then blah blah blah.
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment_references
void complexAlgorithm(ImportantData data) {
  // ... 
}

I can't do this, because comment_references docs say:

two identifiers separated by a period where the first identifier is the name of a class that is in scope and the second is the name of a member declared in the class,

This also impacts model classes generated by freezed – we can't reference fields of the generated freezed class at all, because they mix-in the generated code. For a practical example of why this improvement would be very helpful, please see rrousselGit/freezed#624.

[srawlins]

Thanks for the suggestion. The lint rule actually just enforces that you have written comment references which can be interpreted in the IDE, and by dartdoc, to be references that they can point to. I've moved this over to the SDK, so it can be a request to change the parser to parse more content between [] as a reference, and then dartdoc and IDE tooling can also recognize it.

[bartekpacia]

@srawlins Yeah, the main purpose of why I raised this is to have the references in doc comments to be "clickable" in IDEs :)

[srawlins]

Nice, that's excellent.