Make it more obvious that there's further information behind a property

[Hixie]

For example, look at this page:
https://docs.flutter.io/flutter/material/AppBar-class.html
...it's not at all obvious that if you click "actions" you'll get a lot more information including sample code.

[jcollins-g]

We could dynamically add a link to the one-liner for a property or method if we detect a block code comment that says "Sample Code" or something along those lines?

[Hixie]

The problem occurs even if there's just two paragraphs. For example, look at "alwaysNeedsCompositing" on https://docs.flutter.io/flutter/rendering/RenderObject-class.html.

[jcollins-g]

Hmm. We could produce a [...] link or something if dartdoc detects the one line doc is not all there is?

So the doc line for alwaysNeedsCompositing in the parent class would look like:

Whether this render object always needs compositing. [...]

Open to suggestions as to what the link would look like so it is at the same time obvious, but not intrusive and repetitive looking when there are many of them on a page.

[Hixie]

Worth a try. Anything is better than what we have now, which is that people have no idea there's more text to read. :-)

[devoncarew]

We did used to use ellipses when there was more content. It didn't read great when the doc summary ended with a period (which, most do). I like the [...] idea above, is seems to work well.

[jcollins-g]

OK, I'll try and fit this in, but carefully. If there's one thing I know about changing dartdoc, it is that yes, things could be worse than what we have now. :-)

[Hixie]

Fair enough! :-)

[jcollins-g]

Promoting to P1 as IIRC user studies have indicated this is important.

[jcollins-g]

A sample of the new links, displayed only on items which actually have more useful docs.