Display annotations on fields in dartdoc

[rkj]

This can be very useful for code using framework like Angular that annotate fields with @input and @output to tell semantic of given code.

For example the just published Material widgets:
https://www.dartdocs.org/documentation/angular2_components/0.1.1/angular2_components/GlyphComponent-class.html
there is no way to tell which are actual input fields (the most important piece of API) from regular fields that are used internally by a component.

[Tomucha]

+1, pretty please :-)

[jcollins-g]

Surprising that this wasn't fixed with #1265 but apparently it wasn't. Looking into it.

[jcollins-g]

In some cases, the list of annotations isn't where the dartdoc code expected it to be for certain nodes of the AST. I've figured out how to navigate the tree sufficiently to get some cases, and analyzer issue #28631 covers the rest of them, I hope.

Attached is a screenshot. Is this along the lines of what you were looking for?

[keertip]

Yes, do see the asked for info. Not sure if this is the best way to show it, but lets go with this for now.

[jcollins-g]

https://github.com/dart-lang/dartdoc/tree/1268-display-annotations-on-field

Not usable yet as it depends on https://codereview.chromium.org/2704933002 for analyzer.

Here are a couple more screenshots showing more complex examples from Angular:

[devoncarew]

Awesome!

We may want to render the annotations with a leading @, in order to help users know what they are when scanning the list of fields and methods.

[jcollins-g]

Currently, other annotations have the @ intentionally stripped (protected, deprecated, etc). I don't know whether it is clearer to have them or not (I'm actually for adding the @), but I'd like to be consistent.

I will modify this to return the @ in front of all annotations unless there is a strong objection, then.

Also, this change fixes minor bugs in the prior fix for #1265 , including the appearance of spurious @ symbols in place of parameter annotations in constructor documentation.

[jcollins-g]

Branch now has cleaned up code and tests, but waiting for analyzer 0.29 change to land and be released before mailing as a PR.

[jcollins-g]

Obligatory screenshot, now with extra @ symbols:

[devoncarew]

+1 to the @ symbols :)

[keertip]

Looks good!

[Tomucha]

@jcollins-g since you are in this part of the dartdoc code, please have look on this:
#1162

It's very annoying and possibly dangerous. Thank you!!!

[jcollins-g]

This refactoring of how annotations are handled will fix #1081, #1162 and issues not quite covered in the fix to #1265.