From d226b1aa39fbc6ceb4eba3ded23786be8ee080e8 Mon Sep 17 00:00:00 2001 From: Nate Bosch Date: Wed, 28 Aug 2024 17:49:18 -0700 Subject: [PATCH] Fix doc comments (dart-lang/html#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. --- pkgs/html/lib/parser.dart | 47 +++++++++++++++--------- pkgs/html/lib/src/html_input_stream.dart | 2 +- pkgs/html/lib/src/list_proxy.dart | 2 +- 3 files changed, 32 insertions(+), 19 deletions(-) diff --git a/pkgs/html/lib/parser.dart b/pkgs/html/lib/parser.dart index 749859890..95aaa9a63 100644 --- a/pkgs/html/lib/parser.dart +++ b/pkgs/html/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] of bytes or an [HtmlTokenizer]. +/// Parse an html5 document into a tree. +/// +/// The [input] can be a `String`, a `List` 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] 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` 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] of bytes or an [HtmlTokenizer]. + /// Create and configure an HtmlParser. + /// + /// The [input] can be a `String`, a `List` 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']) { diff --git a/pkgs/html/lib/src/html_input_stream.dart b/pkgs/html/lib/src/html_input_stream.dart index abae4cfb8..b093d3ce3 100644 --- a/pkgs/html/lib/src/html_input_stream.dart +++ b/pkgs/html/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] containing the raw + /// [source] can be either a `String` or a `List` containing the raw /// bytes. /// /// The optional encoding parameter must be a string that indicates diff --git a/pkgs/html/lib/src/list_proxy.dart b/pkgs/html/lib/src/list_proxy.dart index 9ed878309..f226d7f7b 100644 --- a/pkgs/html/lib/src/list_proxy.dart +++ b/pkgs/html/lib/src/list_proxy.dart @@ -4,7 +4,7 @@ library; import 'dart:collection'; abstract class ListProxy extends ListBase { - /// The inner [List] with the actual storage. + /// The proxied list with actual storage. final List _list = []; @override