Add javadoc for domain objects

Author: cuzfrog

doc/Development.md

@@ -1,5 +1,19 @@
 # Development Guide
 
+## Architecture
+
+`Source code` ==Parser=> `Type definition` + `unresolved types` ==Resolver=> `Type definition` + `resolved types` ==Writer=> `target schema/language`
+
+Internal types also have javadoc for more information.
+#### Project structure
+* `annotation` contains the annotation type `@SharedType` as client code compile-time dependency.
+* `processor` contains annotation processor logic, put on client's annotation processing path.
+* `internal` contains domain types used in `processor` and integration test.
+* `it` contains integration tests, which do metadata verification by deserializing metadata objects.
+    * `java8` contains major types for tests.
+    * `java17` uses symlink to reuse types in `java8` then does more type checks, e.g. for Java `record`.
+* `client-test` contains target languages' tests respectively against generated code.
+
 ## Setup
 **Linux is assumed**. If you use Windows, you can use WSL with a remotely connected IDE. Windows 11 supports GUI app inside WSL.
 
@@ -11,45 +25,40 @@ Optionally mount tmpfs to save your disk by:
 ```bash
 ./mount-tmpfs.sh
 ```
-
-## Style check
-```bash
-./mvnw editorconfig:check
-```
-
-## Debug
-Debug annotation processor by run maven build:
-```bash
-./mvnd <your args goes here>
-```
-Then attach your debugger on it.
-
-## Run test
+## Development
+### Run test
 If you encounter compilation problems with your IDE, delegate compilation to maven.
 Before run test in IDE/individual module, run `./mvnw clean install -DskipTests` to build dependency classes.
-
 #### E.g. run integration test locally:
 ```bash
 ./mvnw clean install -DskipTests -q && ./mvnw test -pl it/java17 -pl it/java8
 ```
-
 #### Run local verification with all java tests
 ```bash
 ./mvnw verify
 ```
-
 #### Verify JDK8 compatibility locally
-Setup `JAVA8_HOME` to point to your Java8 installation.
+Setup `JAVA8_HOME` to point to your Java8 installation. Open a new terminal and run:
 ```bash
 . setenv 8
 ./mvnw verify -pl it/java8
 ```
-
 #### Run client tests locally
 Client tests are run in target languages in respective dir inside `./client-test`. They do basic type checking.
 * Typescript. `. setenv && npm i && npm run test`
+#### Misc
+Style check:
+```bash
+./mvnw editorconfig:check
+```
+Debug annotation processor by run maven build:
+```bash
+./mvnd <your args goes here>
+```
+Then attach your debugger on it.
 
 
 ## Coding Style Guide
 1. since annotation processing is one shot execution, JIT is not likely to optimize the code. So prefer plain loop than long calling stacks like Stream chains.
 2. no adding dependencies without strong justification.
+3. Lombok is used in this project, but do not abuse. Only use it to replace unavoidable boilerplate code, and not to increase the bytecode size.

internal/src/main/java/org/sharedtype/domain/ArrayTypeInfo.java

@@ -3,6 +3,16 @@
 import lombok.EqualsAndHashCode;
 import lombok.RequiredArgsConstructor;
 
+/**
+ * Represents an array-like type.
+ * During parsing, a predefined array-like type and its subtypes is captured as this class.
+ * A type will be recognized as this type with higher priority than {@link ConcreteTypeInfo}.
+ * <br>
+ * Predefined array-like types can be configured in global properties. Default is {@link java.lang.Iterable}.
+ *
+ * @see ConcreteTypeInfo
+ * @author Cause Chung
+ */
 @RequiredArgsConstructor
 @EqualsAndHashCode
 public final class ArrayTypeInfo implements TypeInfo {

internal/src/main/java/org/sharedtype/domain/ClassDef.java

@@ -9,7 +9,9 @@
 import java.util.stream.Collectors;
 
 /**
- * Represents info captured from an interface, class, or record.
+ * Represents structural info captured from an interface, class, or record.
+ *
+ * @author Cause Chung
  */
 @Builder
 @EqualsAndHashCode(of = "qualifiedName")
@@ -77,13 +79,13 @@ public String toString() {
     }
 
     private String typeVariablesToString() {
-        return typeVariables.isEmpty() ? "" : "<" + String.join(",", typeVariables.stream().map(TypeVariableInfo::toString).collect(Collectors.toList())) + ">";
+        return typeVariables.isEmpty() ? "" : "<" + typeVariables.stream().map(TypeVariableInfo::toString).collect(Collectors.joining(",")) + ">";
     }
 
     private String supertypesToString() {
         if (supertypes.isEmpty()) {
             return "";
         }
-        return " extends " + String.join(" & ", supertypes.stream().map(t -> t + (t.resolved() ? "" : "?")).collect(Collectors.toList()));
+        return " extends " + supertypes.stream().map(t -> t + (t.resolved() ? "" : "?")).collect(Collectors.joining(" & "));
     }
 }

internal/src/main/java/org/sharedtype/domain/ComponentInfo.java

@@ -2,6 +2,11 @@
 
 import java.io.Serializable;
 
+/**
+ * Represents internal components in a {@link TypeDef}.
+ *
+ * @author Cause Chung
+ */
 public interface ComponentInfo extends Serializable {
     boolean resolved();
 }

internal/src/main/java/org/sharedtype/domain/ConcreteTypeInfo.java

@@ -7,6 +7,14 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * Represents a primitive type or object type that requires its target representation,
+ * and is not recognized as an array-like type.
+ * Like {@link java.lang.String} in typescript as "string", int in typescript as "number".
+ *
+ * @see ArrayTypeInfo
+ * @author Cause Chung
+ */
 @EqualsAndHashCode(of = "qualifiedName")
 @Builder
 public final class ConcreteTypeInfo implements TypeInfo {

internal/src/main/java/org/sharedtype/domain/ConstantInfo.java

@@ -1,5 +1,11 @@
 package org.sharedtype.domain;
 
+/**
+ * Represents a constant literal.
+ * Only literals with values resolvable at compile time are supported.
+ *
+ * @author Cause Chung
+ */
 public final class ConstantInfo {
 
 }

internal/src/main/java/org/sharedtype/domain/Constants.java

@@ -6,6 +6,9 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * @author Cause Chung
+ */
 public final class Constants {
     public static final String ANNOTATION_QUALIFIED_NAME = SharedType.class.getName();
 

internal/src/main/java/org/sharedtype/domain/EnumDef.java

@@ -7,6 +7,11 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * Represents an enum.
+ *
+ * @author Cause Chung
+ */
 @EqualsAndHashCode(of = "qualifiedName")
 @Builder
 public final class EnumDef implements TypeDef {

internal/src/main/java/org/sharedtype/domain/EnumValueInfo.java

@@ -2,7 +2,17 @@
 
 import lombok.EqualsAndHashCode;
 import lombok.RequiredArgsConstructor;
+import org.sharedtype.annotation.SharedType;
 
+/**
+ * Represents an enum value, which is the value in the target code that corresponds to an enum constant.
+ * <br>
+ * By default, enum value is String value of the enum constant. It can be configured with {@link SharedType.EnumValue}.
+ *
+ * @see EnumDef
+ * @see SharedType.EnumValue
+ * @author Cause Chung
+ */
 @EqualsAndHashCode
 @RequiredArgsConstructor
 public final class EnumValueInfo implements ComponentInfo {

internal/src/main/java/org/sharedtype/domain/FieldComponentInfo.java

@@ -5,6 +5,11 @@
 import javax.lang.model.element.Modifier;
 import java.util.Set;
 
+/**
+ * Represents a field or accessor.
+ *
+ * @author Cause Chung
+ */
 @Builder
 public final class FieldComponentInfo implements ComponentInfo {
     private final String name;