Skip to content

Commit 5ecd959

Browse files
PeefyPeefy
authored
Merge pull request #34 from kcl-lang/add-more-comments-for-java-ast
refactor: format and add more documents for java structures
2 parents 3dbbfe0 + 7cc9a9a commit 5ecd959

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

85 files changed

+937
-602
lines changed

‎java/src/main/java/com/kcl/api/API.java‎

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -21,20 +21,16 @@ public API() {
2121
*
2222
* <pre>{@code
2323
*
24-
* import com.kcl.api.*;
25-
* import com.kcl.ast.*;
26-
* import com.kcl.util.JsonUtil;
24+
*import com.kcl.api.*;
25+
*import com.kcl.ast.*;
26+
*import com.kcl.util.JsonUtil;
2727
*
28-
* // Create an instance of the API class
29-
* API api = new API();
30-
* // Parse the program by providing the file paths to the API
31-
* ParseProgram_Result result = api.parseProgram(
32-
* ParseProgram_Args.newBuilder().addPaths("path/to/kcl.k").build()
33-
* );
34-
* // Print the JSON representation of the AST (Abstract Syntax Tree)
35-
* System.out.println(result.getAstJson());
36-
* // Deserialize the JSON string into a Program object
37-
* Program program = JsonUtil.deserializeProgram(result.getAstJson());
28+
*API api = new API();
29+
*ParseProgram_Result result = api.parseProgram(
30+
* ParseProgram_Args.newBuilder().addPaths("path/to/kcl.k").build()
31+
*);
32+
*System.out.println(result.getAstJson());
33+
*Program program = JsonUtil.deserializeProgram(result.getAstJson());
3834
* }</pre>
3935
*
4036
* @param args the arguments specifying the file paths to be parsed.
@@ -70,8 +66,10 @@ public ParseFile_Result parseFile(ParseFile_Args args) throws Exception {
7066
* result.getSymbolsMap().values().forEach(s -> System.out.println(s));
7167
* }</pre>
7268
*
73-
* @param args the arguments specifying the file paths to be parsed and resolved.
74-
* @return the result of parsing the program and parse errors, type errors, including
69+
* @param args the arguments specifying the file paths to be parsed and
70+
* resolved.
71+
* @return the result of parsing the program and parse errors, type errors,
72+
* including
7573
* the AST in JSON format and symbol, type and definition information.
7674
* @throws Exception if an error occurs during the remote procedure call.
7775
*/

‎java/src/main/java/com/kcl/ast/AnyType.java‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,27 @@
22

33
import com.fasterxml.jackson.annotation.JsonTypeName;
44

5-
// AnyType class placeholder
5+
/**
6+
* Any type is the builtin any type annotation.
7+
*
8+
* <p>
9+
* <code>a: any = 1</code>
10+
* </p>
11+
*/
612
@JsonTypeName("Any")
713
public class AnyType extends Type {
814
// Fields and methods specific to AnyType
915
public static enum AnyTypeEnum {
1016
Any
1117
}
1218

19+
AnyTypeEnum value;
20+
1321
public AnyTypeEnum getValue() {
1422
return value;
1523
}
1624

1725
public void setValue(AnyTypeEnum data) {
1826
this.value = data;
1927
}
20-
21-
AnyTypeEnum value;
2228
}

‎java/src/main/java/com/kcl/ast/Arguments.java‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,24 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44
import java.util.List;
55

6-
// Arguments class equivalent in Java
6+
/**
7+
* Arguments, e.g.
8+
*
9+
* <pre>{@code
10+
lambda x: int = 1, y: int = 1 {
11+
x + y
12+
}
13+
* }</pre>
14+
*/
715
public class Arguments {
8-
@JsonProperty("args")
9-
private List<NodeRef<Identifier>> args;
16+
@JsonProperty("args")
17+
private List<NodeRef<Identifier>> args;
1018

11-
@JsonProperty("defaults")
12-
private List<NodeRef<Expr>> defaults; // List can contain nulls to represent Rust's Vec<Option<NodeRef<Expr>>>
19+
@JsonProperty("defaults")
20+
private List<NodeRef<Expr>> defaults; // List can contain nulls to represent Rust's Vec<Option<NodeRef<Expr>>>
1321

14-
@JsonProperty("ty_list")
15-
private List<NodeRef<Type>> tyList; // List can contain nulls to represent Rust's Vec<Option<NodeRef<Type>>>
22+
@JsonProperty("ty_list")
23+
private List<NodeRef<Type>> tyList; // List can contain nulls to represent Rust's Vec<Option<NodeRef<Type>>>
1624

1725
public List<NodeRef<Identifier>> getArgs() {
1826
return args;
@@ -37,7 +45,4 @@ public List<NodeRef<Type>> getTyList() {
3745
public void setTyList(List<NodeRef<Type>> tyList) {
3846
this.tyList = tyList;
3947
}
40-
41-
// Constructor, getters, and setters...
42-
// Additional methods as per Rust impl
4348
}

‎java/src/main/java/com/kcl/ast/AssertStmt.java‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,22 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44
import com.fasterxml.jackson.annotation.JsonTypeName;
55

6-
// AssertStmt class equivalent in Java
6+
/**
7+
* AssertStmt represents an assert statement, e.g.
8+
* <p>
9+
* <code>assert True if condition, "Assert failed message"</code>
10+
* </p>
11+
*/
712
@JsonTypeName("Assert")
813
public class AssertStmt extends Stmt {
9-
@JsonProperty("test")
10-
private NodeRef<Expr> test;
14+
@JsonProperty("test")
15+
private NodeRef<Expr> test;
1116

12-
@JsonProperty("if_cond")
13-
private NodeRef<Expr> ifCond;
17+
@JsonProperty("if_cond")
18+
private NodeRef<Expr> ifCond;
1419

15-
@JsonProperty("msg")
16-
private NodeRef<Expr> msg;
20+
@JsonProperty("msg")
21+
private NodeRef<Expr> msg;
1722

1823
public NodeRef<Expr> getTest() {
1924
return test;
@@ -38,6 +43,4 @@ public NodeRef<Expr> getMsg() {
3843
public void setMsg(NodeRef<Expr> msg) {
3944
this.msg = msg;
4045
}
41-
42-
// Constructor, getters, and setters...
4346
}

‎java/src/main/java/com/kcl/ast/AssignStmt.java‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,27 @@
44

55
import java.util.List;
66

7-
// AssignStmt class equivalent in Java
7+
/**
8+
* AssignStmt represents an assignment, e.g.
9+
* <p>
10+
* <code>a: int = 1</code>
11+
* </p>
12+
* <p>
13+
* <code>a = 1</code>
14+
* </p>
15+
* <p>
16+
* <code>a = b = 1</code>
17+
* </p>
18+
*/
819
public class AssignStmt extends Stmt {
9-
@JsonProperty("targets")
10-
private List<NodeRef<Identifier>> targets;
20+
@JsonProperty("targets")
21+
private List<NodeRef<Identifier>> targets;
1122

12-
@JsonProperty("value")
13-
private NodeRef<Expr> value;
23+
@JsonProperty("value")
24+
private NodeRef<Expr> value;
1425

15-
@JsonProperty("ty")
16-
private NodeRef<Type> ty; // This is optional in Rust, so it can be null in Java
26+
@JsonProperty("ty")
27+
private NodeRef<Type> ty;
1728

1829
public List<NodeRef<Identifier>> getTargets() {
1930
return targets;
@@ -38,6 +49,4 @@ public NodeRef<Type> getTy() {
3849
public void setTy(NodeRef<Type> ty) {
3950
this.ty = ty;
4051
}
41-
42-
// Constructor, getters, and setters...
4352
}

‎java/src/main/java/com/kcl/ast/AstIndex.java‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
@JsonSerialize
1111
@JsonDeserialize
1212
public class AstIndex {
13-
public UUID getId() {
13+
public UUID getId() {
1414
return id;
1515
}
1616

@@ -20,9 +20,9 @@ public void setId(UUID id) {
2020

2121
private UUID id;
2222

23-
public AstIndex() {
24-
this.id = UUID.randomUUID();
25-
}
23+
public AstIndex() {
24+
this.id = UUID.randomUUID();
25+
}
2626

2727
@Override
2828
public int hashCode() {
@@ -48,6 +48,4 @@ public boolean equals(Object obj) {
4848
return false;
4949
return true;
5050
}
51-
52-
// Getters and setters...
5351
}

‎java/src/main/java/com/kcl/ast/AugAssignStmt.java‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,25 @@
33
import com.fasterxml.jackson.annotation.JsonProperty;
44
import com.fasterxml.jackson.annotation.JsonTypeName;
55

6-
// AugAssignStmt class equivalent in Java
6+
/**
7+
* AugAssignStmt represents an argument assignment, e.g.
8+
* <p>
9+
* <code>a += 1</code>
10+
* </p>
11+
* <p>
12+
* <code>a -= 1</code>
13+
* </p>
14+
*/
715
@JsonTypeName("AugAssign")
816
public class AugAssignStmt extends Stmt {
9-
@JsonProperty("target")
10-
private NodeRef<Identifier> target;
17+
@JsonProperty("target")
18+
private NodeRef<Identifier> target;
1119

12-
@JsonProperty("value")
13-
private NodeRef<Expr> value;
20+
@JsonProperty("value")
21+
private NodeRef<Expr> value;
1422

15-
@JsonProperty("op")
16-
private AugOp op;
23+
@JsonProperty("op")
24+
private AugOp op;
1725

1826
public NodeRef<Identifier> getTarget() {
1927
return target;
@@ -38,6 +46,4 @@ public AugOp getOp() {
3846
public void setOp(AugOp op) {
3947
this.op = op;
4048
}
41-
42-
// Constructor, getters, and setters...
4349
}

‎java/src/main/java/com/kcl/ast/AugBinOrAugOp.java‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
@JsonTypeName("Aug")
66
public class AugBinOrAugOp extends BinOrAugOp {
7-
public AugOp getOp() {
7+
public AugOp getOp() {
88
return op;
99
}
1010

@@ -13,6 +13,4 @@ public void setOp(AugOp op) {
1313
}
1414

1515
private AugOp op;
16-
17-
// Constructor, getters, and setters...
1816
}

‎java/src/main/java/com/kcl/ast/AugOp.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
package com.kcl.ast;
22

3-
// AugOp enum equivalent in Java
43
public enum AugOp {
54
Assign("="),
65
Add("+="),
@@ -25,7 +24,7 @@ public enum AugOp {
2524
public String symbol() {
2625
return symbol;
2726
}
28-
27+
2928
// Method to convert AugOp to BinOp, if possible
3029
public BinOp toBinOp() throws IllegalArgumentException {
3130
switch (this) {

‎java/src/main/java/com/kcl/ast/BasicType.java‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22

33
import com.fasterxml.jackson.annotation.JsonTypeName;
44

5-
// BasicType enum equivalent in Java
65
@JsonTypeName("Basic")
76
public class BasicType extends Type {
87
public static enum BasicTypeEnum {

0 commit comments

Comments
 (0)