Resolve how to document complex metadata (like @ViewChildren)

[matanlurey]

It was brought up several internal and external requests that the current documentation was not useful (it contained out-of-date examples; also tracked here: #1267 and #996) and didn't document all of the features and caveats of the annotation.

I addressed the latter issue here #1462, but @alorenzen correctly brought up that this is very much a stop-gap, we should figure out how to update our documentation at HEAD and/or be consistent in use of markdown files, or something like it (#942).

[alorenzen]

So I think there are two issues here.

The first issue is that the examples themselves were out of date. That could be solved by using the tools proposed in #1395 to automatically inline real examples into docs.

The second issue is that the dartdoc itself is too long in this case. I think we probably need an article (markdown file in our docs/ folder) specifically for ViewChildren/ContentChildren. There are a lot of nuance there that needs to be addressed, and dartdoc is not necessarily the place. Having the dartdoc link to the larger article is probably necessary for discovery purposes.

[matanlurey]

I agree. Lets keep this open until we have a resolution to #1395 and figure out where to put our larger articles and/or how we will keep them updated. I still think we should get that larger PR in versus not.

[matanlurey]

Using live snippets.