Doc generated for the immutable annotation could be more helpful

[HansMuller]

We've just marked many (more) Flutter classes immutable: https://github.com/flutter/flutter/pull/9462. Hopefully that will make our API easier to understand.

Currently the doc generated for immutable classes just says:

annotations: @immutable

I think it would be helpful if dartdoc provided a short boilerplate statement about what immutable means, and link to a longer discussion about what the implications are, when to use it, etc.

[sethladd]

Good idea!

[srawlins]

Can you show an example page of a ~~constructor~~ class annotated with @immutable?

[srawlins]

Curve is one example.

I super agree; annotations should at least be visually higher than the list of Inheritance and Implementers.