Skip to content

L3: attach body-internal comments to statement nodes #190

Description

@sinha108

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

  • Attach each body-internal comment to the statement node it precedes (or is trailing on)
  • Decide and record the shape: a comments list on the body node, consistent with declaration nodes
  • Comments in a callable with no statements (e.g. an empty body) still have a home, or are documented as intentionally dropped
  • Re-run the v1/v2 comparison and confirm the comment delta closes to duplication-only

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.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions