Fix doc comments

[natebosch]

Update comments that set off a false positive in the
unintended_html_in_doc_comment lint. For references to core Dart
types with generics, replace the square braces with backticks since it
isn't useful to constantly link them.

For the comments that are edited, and a few nearby, update for style:

• Separate out a header as it's own paragraph.
• Reduce repetitive phrasing and redundant links to the same arguments.

Use a trailing comma for a long argument list, and re-order the
arguments so that the always-useful arguments are at the top, and the
arguments only pertaining to certain uses follow.