Move doc directive documentation to source code

[srawlins]

This documentation currently lives in the wiki. However, we are planning to move the dartdoc code to the Dart SDK repo, and this wiki will be going away.

The text in this PR is more-or-less a dump of the wiki contents, and I tweaked the wording and typos a bit.

A full review of the text is fine, but I will likely respond for requests to document "more" or document "better" by writing in TODOs. I still encourage a full read of the text.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[parlough]

Cool!

For non-deprecated directives that are well supported, especially the ones now supported by the analyzer, I've long dreamt of their docs living on dart.dev (dart-lang/site-www#4347).

Perhaps a full review of the text can wait until that is worked on?

[srawlins]

Thanks for the link @parlough !! I like this direction. I think we could maybe document each directive one-by-one, where we can focus on getting the text and semantics and support correct.

[parlough]

That sounds great to me.

I mostly delayed that work since I wasn't sure if and in what way each directive would stick around. Same for how the comment references could change with the import work.

[bwilkerson]

Nice.