Problem
v2 attaches each comment to exactly one node — the declaration it documents — which fixes v1's duplication (v1 used getAllContainedComments(), repeating a method's comment onto its type and compilation unit: a 2.09x factor on spring-petclinic). But comments inside method bodies have no declaration to attach to, so they are absent from the tree entirely. Measured at roughly 47 distinct comments per application (docs/design/notes/l1-v1-v2-comparison.md).
They remain recoverable from module.source, but they are not addressable or queryable — which matters for doc-driven and LLM consumers.
Scope boundary
Attaching body-internal comments to the statement nodes that L3 introduces. Depends on #183 (L3 populates body with statements); there is no node to attach them to before that. Does not revisit declaration comments, which are already correct.
Goals
Caveats and known risks
- Attachment is heuristic: JavaParser associates a comment with the following node, but a trailing end-of-line comment belongs to the preceding one. Pick a rule and document it.
- Do not reintroduce v1's duplication: a comment must appear on exactly one node.
Definition of done
- The comparison report's comment delta is explained entirely by v1 duplication, with no distinct comment missing from v2.
Problem
v2 attaches each comment to exactly one node — the declaration it documents — which fixes v1's duplication (v1 used
getAllContainedComments(), repeating a method's comment onto its type and compilation unit: a 2.09x factor onspring-petclinic). But comments inside method bodies have no declaration to attach to, so they are absent from the tree entirely. Measured at roughly 47 distinct comments per application (docs/design/notes/l1-v1-v2-comparison.md).They remain recoverable from
module.source, but they are not addressable or queryable — which matters for doc-driven and LLM consumers.Scope boundary
Attaching body-internal comments to the statement nodes that L3 introduces. Depends on #183 (L3 populates
bodywith statements); there is no node to attach them to before that. Does not revisit declaration comments, which are already correct.Goals
commentslist on the body node, consistent with declaration nodesCaveats and known risks
Definition of done