Emphasise required arguments

[Hixie]

Consider this documentation:
https://docs.flutter.io/flutter/material/PopupMenuButton/PopupMenuButton.html

It's not at all clear from the top part that itemBuilder is required, whereas the others are optional.

From flutter/flutter#10170.

[jcollins-g]

adding @required to the top section would probably solve this.

As an aside, I'm also a little weirded out by the inclusion of something that is the source but isn't, and by something that is the actual source in our dartdocs. It seems to me that having two different sections here is only useful in case the first one is misleading or broken -- I'd like to try to fix that.

[Hixie]

The main thing I want from the top block is the types of each argument, which aren't necessarily obvious from the source itself. What would be really cool would be if the top one, rather than being a source-like blob, was a pretty table that listed each argument, whether it was a named argument or positional or optional or required or whatever, its type, its default value, and ideally any dartdocs from the relevant field in the case of the argument being a this.foo-style argument.

But that's probably something for another bug. :-)

[jcollins-g]

There are a couple references to this issue now, suggesting it's pretty important to the developer experience for Flutter. Raising to P1.

[jcollins-g]

There was a TODO where I special-cased attributes out of parameters deliberately to be bug-for-bug compatible when I enhanced the annotation support, but I wasn't sure whether that was a good idea.

Apparently it wasn't. Screenshot below:

[Hixie]

Yay!

(I'll fork out my suggestion for a table to a separate P3 bug.)

[Hixie]

(Filed #1451)