[Records] dartdoc implemention

[itsjustkevin]

No description provided.

[srawlins]

Largely complete in #3233; leaving open for remaining tasks.

[vsmenon]

@srawlins - do we have anything to do here?

[srawlins]

Hmm, yikes, I have no idea what I meant by "leaving open for remaining tasks." This may not be complete.

[jcollins-g]

@srawlins One task that I can see is that there's no bit in test_package_experiments that allows us to check the integration of the feature. Adding that may also help me discover what was meant by "remaining tasks", if any others exist.

[srawlins]

You could add that. I have been writing all new tests as unit tests instead of using the testing/ folder.

[jcollins-g]

@srawlins. Saw that. That's probably for the best for most cases. Having something browsable helps make sure we didn't miss anything as I don't trust my brain to render all the test HTML as well as an actual web browser.

[jcollins-g]

Two things so far I've found that need to be fixed:

• The record type rendering is not very legible, and while it looks Dart-like would not be able to reproduce the type.

The type for this variable should be written out as (int, double, c: String, d: int) to match how a type for this variable would be declared.

• We are not preserving the typedef name in the case of records. While that matches the underlying implementation it is probably not in line with user expectations/friendliness.

Given source:

RecordTypedef<double> fromParameterizedRecordType = (3.5, 10, "A string");

I would expect RecordTypedef<double> to be the type of fromParameterizedRecordType, with linking.
Contrast (double, int, String), or the current Record(double $0, int $1, String $2).

[srawlins]

As long as we stay in-line with the handling of other typedefs, SG.

[jcollins-g]

As long as we stay in-line with the handling of other typedefs, SG.

The second item (preserving typedef names) seems the most clearly in line with other typedef handling, so doing that first. I'll do some checking to make sure my plan for the first item remains consistent.

[jcollins-g]

This should be complete with #3344; any problems discovered later can be separate issues.