[v1] Add javadoc for AST; refactor of ExprVarRef scope

[alancai98]

Relevant Issues

• [v1] Replace sprout-generated AST with hand-written AST #1610

Description

• Adds javadocs for hand-written AST classes
• Removes the lombok getters in favor of hand-written getters since the lombok-annotated @Getters were not included in the javadoc

Other Information

• Updated Unreleased Section in CHANGELOG: [NO]

• Any backward-incompatible changes? [YES]

• Any new external dependencies? [NO]

• Do your changes comply with the Contributing Guidelines
  and Code Style Guidelines? [YES]

License Information

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[github-actions]

CROSS-ENGINE-REPORT ❌

	BASE (LEGACY-V0.14.8)	TARGET (EVAL-549694F)	+/-
% Passing	89.67%	94.56%	4.88% ✅
Passing	5287	5575	288 ✅
Failing	609	47	-562 ✅
Ignored	0	274	274 🔶
Total Tests	5896	5896	0 ✅

Testing Details

• Base Commit: v0.14.8
• Base Engine: LEGACY
• Target Commit: 549694f
• Target Engine: EVAL

Result Details

• ❌ REGRESSION DETECTED. See Now Failing/Ignored Tests. ❌
• Passing in both: 2644
• Failing in both: 17
• Ignored in both: 0
• PASSING in BASE but now FAILING in TARGET: 2
• PASSING in BASE but now IGNORED in TARGET: 108
• FAILING in BASE but now PASSING in TARGET: 180
• IGNORED in BASE but now PASSING in TARGET: 0

Now FAILING Tests ❌

The following 2 test(s) were previously PASSING in BASE but are now FAILING in TARGET:

Click here to see

1. inPredicateWithTableConstructor, compileOption: PERMISSIVE
2. notInPredicateWithTableConstructor, compileOption: PERMISSIVE

Now IGNORED Tests ❌

The complete list can be found in GitHub CI summary, either from Step Summary or in the Artifact.

Now Passing Tests

180 test(s) were previously failing in BASE (LEGACY-V0.14.8) but now pass in TARGET (EVAL-549694F). Before merging, confirm they are intended to pass.

The complete list can be found in GitHub CI summary, either from Step Summary or in the Artifact.

CROSS-COMMIT-REPORT ✅

	BASE (EVAL-71E9EE3)	TARGET (EVAL-549694F)	+/-
% Passing	94.56%	94.56%	0.00% ✅
Passing	5575	5575	0 ✅
Failing	47	47	0 ✅
Ignored	274	274	0 ✅
Total Tests	5896	5896	0 ✅

Testing Details

• Base Commit: 71e9ee3
• Base Engine: EVAL
• Target Commit: 549694f
• Target Engine: EVAL

Result Details

• Passing in both: 5575
• Failing in both: 47
• Ignored in both: 274
• PASSING in BASE but now FAILING in TARGET: 0
• PASSING in BASE but now IGNORED in TARGET: 0
• FAILING in BASE but now PASSING in TARGET: 0
• IGNORED in BASE but now PASSING in TARGET: 0

[alancai98]

(self-review) potential issue w/ the @Getter (and also @Builder) annotation is that they are not included in the generated Javadoc. So in this PR, I ended up using delombok to add the hand-written getters. Some of the getters did have some useful javadoc (especially related to boolean parameters), so including it in the javadoc can be helpful for consumers.

We could apply the same in the future to @Builders if there's a need.

[alancai98]

(self-review) simplification of var ref modeling comes from this prior PR comment -- #1688 (comment). No need to have a separate enum to model the @T vs T var ref.

[alancai98]

(self-review) left out the javadoc for most of the

• getters
• static enum constructor methods
• default constructors

imo, those functions and constructor arguments are pretty self-explanatory.

[RCHowell]

Docs look good enough, thanks for doing this big effort.

[RCHowell]

Suggested change

	* Base abstract class representing enums in the AST.
	* Abstract base class representing enums in the AST.

[alancai98]

Ack, I'll change in a few other places as well.