Paul King created GROOVY-11939:
----------------------------------
Summary: Consolidate inline-tag processing in SimpleGroovyClassDoc
Key: GROOVY-11939
URL: https://issues.apache.org/jira/browse/GROOVY-11939
Project: Groovy
Issue Type: Improvement
Reporter: Paul King
{{org.codehaus.groovy.tools.groovydoc.SimpleGroovyClassDoc}} currently handles
Javadoc-style inline and block tags via multiple regex passes run in sequence.
The file is ~1050 LOC and compiles ~60 `Pattern` instances; each tag type
(\{@link}, \{@code}, \{@literal}, block tags like @see / @return / @param /
@throws / @author / @since) runs its own scan-and-replace over the doc text
with string concatenation in the loop. `GroovyRootDocBuilder.replaceTags`
duplicates a subset of this for package-info handling, flagged by a `// TODO
remove dup with SimpleGroovyClassDoc` at line 173.
Several planned groovydoc enhancements each add another inline tag that would,
in the current model, bolt on yet another regex pass:
- GROOVY-6016 — \{@value} inline tag
- GROOVY-3782 — \{@inheritDoc} inline tag (plus a stray-"{" rendering glitch
that is a symptom of the current regex approach)
- GROOVY-11938 — \{@snippet} per JEP 413 (attribute parsing, verbatim body,
markup-comment mini-parser)
- GROOVY-11542 — JEP 467 Markdown doc comments (CommonMark reference links such
as [java.util.HashMap] / [text][#ref] need the same FQN-to-URL resolution
currently inside getDocUrl / link handling)
h2. Proposed approach
Replace the multi-pass regex rewriter with a single-pass tokenizer over doc
text. The tokenizer yields a stream of TEXT / INLINE_TAG(name, body) /
BLOCK_TAG(name, body) tokens; each tag has a dedicated adapter responsible for
rendering. Tag dispatch becomes a registry lookup. The cost of adding a new tag
drops from "write another regex and splice it into the pipeline at the right
spot" to "register one adapter".
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
