Fix doc comments (#256)

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.

lib/parser.dart

@@ -26,8 +26,10 @@ import 'src/tokenizer.dart';
 import 'src/treebuilder.dart';
 import 'src/utils.dart';
 
-/// Parse the [input] html5 document into a tree. The [input] can be
-/// a [String], [List<int>] of bytes or an [HtmlTokenizer].
+/// Parse an html5 document into a tree.
+///
+/// The [input] can be a `String`, a `List<int>` of bytes, or an
+/// [HtmlTokenizer].
 ///
 /// If [input] is not a [HtmlTokenizer], you can optionally specify the file's
 /// [encoding], which must be a string. If specified that encoding will be
@@ -44,9 +46,12 @@ Document parse(dynamic input,
   return p.parse();
 }
 
-/// Parse the [input] html5 document fragment into a tree. The [input] can be
-/// a [String], [List<int>] of bytes or an [HtmlTokenizer]. The [container]
-/// element can optionally be specified, otherwise it defaults to "div".
+/// Parse an html5 document fragment into a tree.
+///
+/// The [input] can be a `String`, a `List<int>` of bytes, or an
+/// [HtmlTokenizer].
+/// The [container] element can optionally be specified, otherwise it defaults
+/// to "div".
 ///
 /// If [input] is not a [HtmlTokenizer], you can optionally specify the file's
 /// [encoding], which must be a string. If specified, that encoding will be used,
@@ -126,8 +131,13 @@ class HtmlParser {
   late final _afterAfterBodyPhase = AfterAfterBodyPhase(this);
   late final _afterAfterFramesetPhase = AfterAfterFramesetPhase(this);
 
-  /// Create an HtmlParser and configure the [tree] builder and [strict] mode.
-  /// The [input] can be a [String], [List<int>] of bytes or an [HtmlTokenizer].
+  /// Create and configure an HtmlParser.
+  ///
+  /// The [input] can be a `String`, a `List<int>` of bytes, or an
+  /// [HtmlTokenizer].
+  ///
+  /// The [strict], [tree] builder, and [generateSpans] arguments configure
+  /// behavior for any type of input.
   ///
   /// If [input] is not a [HtmlTokenizer], you can specify a few more arguments.
   ///
@@ -141,16 +151,17 @@ class HtmlParser {
   /// automatic conversion of element and attribute names to lower case. Note
   /// that standard way to parse HTML is to lowercase, which is what the browser
   /// DOM will do if you request `Element.outerHTML`, for example.
-  HtmlParser(dynamic input,
-      {String? encoding,
-      bool parseMeta = true,
-      bool lowercaseElementName = true,
-      bool lowercaseAttrName = true,
-      this.strict = false,
-      this.generateSpans = false,
-      String? sourceUrl,
-      TreeBuilder? tree})
-      : tree = tree ?? TreeBuilder(true),
+  HtmlParser(
+    dynamic input, {
+    TreeBuilder? tree,
+    this.strict = false,
+    this.generateSpans = false,
+    String? encoding,
+    bool parseMeta = true,
+    bool lowercaseElementName = true,
+    bool lowercaseAttrName = true,
+    String? sourceUrl,
+  })  : tree = tree ?? TreeBuilder(true),
         tokenizer = input is HtmlTokenizer
             ? input
             : HtmlTokenizer(input,
@@ -166,6 +177,7 @@ class HtmlParser {
   bool get innerHTMLMode => innerHTML != null;
 
   /// Parse an html5 document into a tree.
+  ///
   /// After parsing, [errors] will be populated with parse errors, if any.
   Document parse() {
     innerHTML = null;
@@ -174,6 +186,7 @@ class HtmlParser {
   }
 
   /// Parse an html5 document fragment into a tree.
+  ///
   /// Pass a [container] to change the type of the containing element.
   /// After parsing, [errors] will be populated with parse errors, if any.
   DocumentFragment parseFragment([String container = 'div']) {

lib/src/html_input_stream.dart

@@ -48,7 +48,7 @@ class HtmlInputStream {
   /// HtmlInputStream(source, [encoding]) -> Normalized stream from source
   /// for use by html5lib.
   ///
-  /// [source] can be either a [String] or a [List<int>] containing the raw
+  /// [source] can be either a `String` or a `List<int>` containing the raw
   /// bytes.
   ///
   /// The optional encoding parameter must be a string that indicates

lib/src/list_proxy.dart

@@ -4,7 +4,7 @@ library;
 import 'dart:collection';
 
 abstract class ListProxy<E> extends ListBase<E> {
-  /// The inner [List<T>] with the actual storage.
+  /// The proxied list with actual storage.
   final List<E> _list = <E>[];
 
   @override