26 conflict name (#40)

* Write to qualified name in JavaSerializationFileWriter

* Error on name conflict for typescript

* Add javadoc for domain objects

Author: cuzfrog

.editorconfig

@@ -15,3 +15,6 @@ ij_java_imports_layout = *,|,javax.**,java.**,|,$*
 
 [*.yaml]
 indent_size = 2
+
+[*.ts]
+ij_javascript_enforce_trailing_comma = whenmultiline

README.md

@@ -16,8 +16,8 @@
 * [vojtechhabarta/typescript-generator](https://github.com/vojtechhabarta/typescript-generator)
 
 ## Documentation
-[User Guide](doc/Usage.md)
-[Development Guide](doc/Development.md)
+* [User Guide](doc/Usage.md)
+* [Development Guide](doc/Development.md)
 
 ## Authors
 Cause Chung ([email protected])

annotation/src/main/java/org/sharedtype/annotation/SharedType.java

@@ -7,9 +7,12 @@
 import java.lang.annotation.Target;
 
 /**
+ * <p>Share a type. <a href="https://github.com/cuzfrog/SharedType">Website</a></p>
+ * <br>
  * <b>Inner class:</b>
  * <p>
  * Declared inner and nested types will not be included by default, unless they are referenced by other types.
+ * Non-static inner classes are not supported, see documentation for details.
  *     TODO: doc for nested types
  * </p>
  *
@@ -20,7 +23,17 @@
 @Documented
 public @interface SharedType {
     /**
-     * The name of the emitted type. If not specified, the simple name of the annotated type will be used.
+     * <p>
+     *     The name of the emitted type. If not specified, the simple name of the annotated type will be used.
+     *     This may be used to help avoid conflicting names in target output.
+     * </p>
+     * <br>
+     * <p>
+     *     How possibly conflicting names are resolved:
+     *     <ul>
+     *         <li>Typescript: simple name of a class is used as type name. Duplicate names are not allowed.</li>
+     *     </ul>
+     * </p>
      */
     String name() default "";
 

client-test/typescript/tests/enum-union.ts

@@ -1,4 +1,4 @@
-import type {DependencyClassA, DependencyClassB, DependencyClassC, EnumGalaxy, EnumSize, EnumTShirt, JavaRecord} from "../src/index.js";
+import type {DependencyClassA, DependencyClassB, DependencyClassC, EnumGalaxy, EnumSize, EnumTShirt, JavaRecord, AnotherJavaClass} from "../src/index.js";
 
 export const list1: EnumGalaxy[] = ["Andromeda", "MilkyWay", "Triangulum"];
 export const record1: Record<EnumTShirt, number> = {
@@ -51,3 +51,7 @@ export const obj: Omit<JavaRecord<string, number>, "aVoid" | "genericMap"> = {
     primitiveShort: 0,
     string: "",
 };
+
+export const anotherJavaClass: AnotherJavaClass = {
+    value: 333,
+}

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 {
 
 }