commit b09ecc45bfc1c4ff9a47a87b411e38925864410f
author Sam Rawlins <srawlins@google.com> Wed Sep 20 21:56:50 2023 +0000
committer Commit Queue <dart-scoped@luci-project-accounts.iam.gserviceaccount.com> Wed Sep 20 21:56:50 2023 +0000
tree 35d38de712fdd105e1a359b34315c5222f9f6204
parent e28faa2462422298367c9ef85250090a49a56905

analyzer: Block doc directives

In this CL, we shake things up a bit to separate the idea of a "doc
directive" and a "doc directive tag". The doc comments have been
updated to reflect the change. We have to recognize and support end-
tags, and recover when an end-tag is missing, a start-tag is missing,
or end-tags are out-of-order.

I also introduce a notion of doc directive nesting, in a way that
should not be computationally expensive, nor memory expensive.

Take this text as an example:

/// {@template foo}
/// Text.
/// {@inject-html}
/// <p>Some HTML.</p>
/// {@end-inject-html}
/// {@youtube ... }
/// {@endtemplate}

Notice the doc directives nested in the following way:

* template directive:
  * text: "Text."
  * inject-html directive:
    * text: "<p>Some HTML.</p>"
    * youtube directive

I want to avoid storing any blocks of text on the DocDirective nodes,
to avoid what could be very excessive memory usage. And if I want to
avoid storing the text, I think there is little benefit in storing the
data for these directives in a tree structure. In this CL, the data
is stored in one List, `docDirectives` on the CommentImpl:

* [0] - template directive, with data about its opening tag and
        closing tag.
* [1] - inject-html directive, with data about its opening tag and
        closing tag.
* [2] - youtube tag, with data about its singular tag.

For syntax highlighting purposes, there is no benefit to understanding
the nesting. And dartdoc currently gets all of the comment text from
the AST (or maybe from offsets in the actual text???) so I think there
is currently no downside to not capturing the nesting structure in
the CommentImpl instance.

But I can see in the future it might be better for dartdoc to consume
an API with the nesting structure, and that nesting structure does not
necessarily need to contain a copy of any text; it could contain some
sort of 'Text' data, with offsets of text contained in block doc
directives.

Change-Id: Ib58ab68fe80eea76ee7fa912d00fc69cc74f72d3
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/326883
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>