Merge pull request #64 from fujaba/javadoc

Generated JavaDocs

.palantir/revapi.yml

@@ -9,6 +9,10 @@ acceptedBreaks:
       old: "field org.fulib.classmodel.FileFragmentMap.PACKAGE_NEWLINES"
       new: "field org.fulib.classmodel.FileFragmentMap.PACKAGE_NEWLINES"
       justification: "https://github.com/fujaba/fulib/pull/36"
+    - code: "java.field.constantValueChanged"
+      old: "field org.fulib.parser.FulibClassLexer._serializedATN"
+      new: "field org.fulib.parser.FulibClassLexer._serializedATN"
+      justification: "ANTLR-generated org.fulib.parser classes are for internal use only"
     - code: "java.field.constantValueChanged"
       old: "field org.fulib.parser.FulibClassParser.RULE_annotatedType"
       new: "field org.fulib.parser.FulibClassParser.RULE_annotatedType"

src/gen/java/org/fulib/classmodel/GenModel.java

@@ -14,51 +14,109 @@ public void decorate(ClassModelManager mb)
       final Clazz ClassModel = mb.haveClass("ClassModel", c -> {
          c.attribute("packageName", STRING);
          c.attribute("mainJavaDir", STRING);
-         c.attribute("defaultCollectionType", "CollectionType");
-         c.attribute("defaultPropertyStyle", STRING, "\"POJO\"");
+         c
+            .attribute("defaultCollectionType", "CollectionType")
+            .setDescription("the default collection type for to-n roles")
+            .setSince("1.2");
+         c
+            .attribute("defaultPropertyStyle", STRING, "\"POJO\"")
+            .setDescription("the default property style for attributes and roles.\n"
+                            + "Currently, only {@link Type#POJO}, {@link Type#BEAN} and {@link Type#JAVA_FX} are supported.");
       });
 
       final Clazz Clazz = mb.haveClass("Clazz", c -> {
          c.attribute("name", STRING);
-         c.attribute("propertyStyle", STRING);
-         c.attribute("modified", BOOLEAN);
-         c.attribute("imports", STRING).setCollectionType(CollectionType.LinkedHashSet);
+         c
+            .attribute("propertyStyle", STRING)
+            .setDescription("the default property style for attributes and roles.\n"
+                            + "Currently, only {@link Type#POJO}, {@link Type#BEAN} and {@link Type#JAVA_FX} are supported.");
+         c
+            .attribute("modified", BOOLEAN)
+            .setDescription("a boolean indicating whether this attribute was modified. For internal use only.");
+         c
+            .attribute("imports", STRING)
+            .setCollectionType(CollectionType.LinkedHashSet)
+            .setDescription("the set of imported members.\n"
+                            + "Elements can have one of the formats {@code org.example.Foo}, {@code static org.example.Foo.bar},\n"
+                            + "{@code import org.example.Foo;} or {@code import static org.example.Foo.bar;}")
+            .setSince("1.2");
       });
 
       final Clazz Attribute = mb.haveClass("Attribute", c -> {
          c.attribute("name", STRING);
          c.attribute("type", STRING);
-         c.attribute("collectionType", "CollectionType");
+         c.attribute("collectionType", "CollectionType").setDescription("the collection type").setSince("1.2");
          c.attribute("initialization", STRING);
-         c.attribute("propertyStyle", STRING);
-         c.attribute("modified", BOOLEAN);
+         c
+            .attribute("propertyStyle", STRING)
+            .setDescription("the property style.\n"
+                            + "Currently, only {@link Type#POJO}, {@link Type#BEAN} and {@link Type#JAVA_FX} are supported.");
+         c
+            .attribute("modified", BOOLEAN)
+            .setDescription("a boolean indicating whether this attribute was modified. For internal use only.");
+         c
+            .attribute("description", STRING)
+            .setDescription("the description of this attribute, used for generating JavaDocs")
+            .setSince("1.3");
+         c
+            .attribute("since", STRING)
+            .setDescription("the version when this attribute was introduced, used for generating JavaDocs")
+            .setSince("1.3");
       });
 
       final Clazz AssocRole = mb.haveClass("AssocRole", c -> {
          c.attribute("name", STRING);
          c.attribute("cardinality", INT);
-         c.attribute("collectionType", "CollectionType");
-         c.attribute("aggregation", BOOLEAN);
-         c.attribute("propertyStyle", STRING);
-         c.attribute("modified", BOOLEAN);
+         c.attribute("collectionType", "CollectionType").setDescription("the collection type").setSince("1.2");
+         c
+            .attribute("aggregation", BOOLEAN)
+            .setDescription("a boolean indicating whether this role is an aggregation,\n"
+                            + "i.e. whether the target objects are {@code removeYou}'d completely when using {@code without*} methods or\n"
+                            + "{@code removeYou} on the source object");
+         c
+            .attribute("propertyStyle", STRING)
+            .setDescription("the property style.\n"
+                            + "Currently, only {@link Type#POJO}, {@link Type#BEAN} and {@link Type#JAVA_FX} are supported.");
+         c
+            .attribute("description", STRING)
+            .setDescription("the description of this role, used for generating JavaDocs")
+            .setSince("1.3");
+         c
+            .attribute("since", STRING)
+            .setDescription("the version when this role was introduced, used for generating JavaDocs")
+            .setSince("1.3");
+         c
+            .attribute("modified", BOOLEAN)
+            .setDescription("a boolean indicating whether this role was modified. For internal use only.");
       });
 
       final Clazz FMethod = mb.haveClass("FMethod", c -> {
          c.attribute("methodBody", STRING);
-         c.attribute("modified", BOOLEAN);
-         c.attribute("modifiers", STRING, "\"public\"");
+         c
+            .attribute("modified", BOOLEAN)
+            .setDescription("a boolean indicating whether this method was modified. For internal use only.");
+         c
+            .attribute("modifiers", STRING, "\"public\"")
+            .setDescription("the modifiers. Defaults to \"public\"")
+            .setSince("1.2");
          c.attribute("annotations", STRING);
       });
 
-      mb.associate(ClassModel, "classes", MANY, Clazz, "model", ONE);
+      mb
+         .associate(ClassModel, "classes", MANY, Clazz, "model", ONE)
+         .setDescription("the classes contained in this model")
+         .setSince("1.2");
 
-      mb.associate(Clazz, "attributes", MANY, Attribute, "clazz", ONE);
+      mb.associate(Clazz, "attributes", MANY, Attribute, "clazz", ONE).setDescription("the attributes").setSince("1.2");
 
-      mb.associate(Clazz, "roles", MANY, AssocRole, "clazz", ONE);
+      mb.associate(Clazz, "roles", MANY, AssocRole, "clazz", ONE).setDescription("the roles").setSince("1.2");
 
-      mb.associate(Clazz, "methods", MANY, FMethod, "clazz", ONE);
+      mb.associate(Clazz, "methods", MANY, FMethod, "clazz", ONE).setDescription("the methods").setSince("1.2");
 
-      mb.associate(Clazz, "superClass", ONE, Clazz, "subClasses", MANY);
+      mb
+         .associate(Clazz, "subClasses", MANY, Clazz, "superClass", ONE)
+         .setDescription("the subclasses")
+         .setSince("1.2");
 
       mb.associate(AssocRole, "other", ONE, AssocRole, "other", ONE);
 

src/main/antlr/FulibClass.g4

@@ -149,7 +149,7 @@ DOUBLE: 'double';
 THIS: 'this';
 NEW: 'new';
 
-DOC_COMMENT: '/**' .*? '*/' -> channel(2);
+DOC_COMMENT: '/**' .*? '*/' -> channel(3); // TODO named JAVADOC channel (requires separate lexer + parser grammars)
 BLOCK_COMMENT: '/*' .*? '*/' -> channel(2);
 LINE_COMMENT: '//' .*? '\n' -> channel(2);
 

src/main/java/org/fulib/classmodel/AssocRole.java

@@ -4,6 +4,9 @@
 
 import java.beans.PropertyChangeListener;
 import java.beans.PropertyChangeSupport;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
 import java.util.Objects;
 
 public class AssocRole
@@ -22,6 +25,10 @@ public class AssocRole
    public static final String PROPERTY_modified = "modified";
    public static final String PROPERTY_clazz = "clazz";
    public static final String PROPERTY_other = "other";
+   /** @since 1.3 */
+   public static final String PROPERTY_description = "description";
+   /** @since 1.3 */
+   public static final String PROPERTY_since = "since";
 
    // =============== Fields ===============
 
@@ -34,6 +41,8 @@ public class AssocRole
    private CollectionType collectionType;
    private boolean aggregation;
    private String propertyStyle;
+   private String description;
+   private String since;
    private boolean modified;
 
    // =============== Properties ===============
@@ -171,9 +180,9 @@ public CollectionType getCollectionType()
 
    /**
     * @param value
-    *    the new collection type
+    *    the collection type
     *
-    * @return this instance, to allow method chaining
+    * @return this
     *
     * @since 1.2
     */
@@ -217,7 +226,8 @@ public AssocRole setRoleType(String value)
 
    /**
     * @return a boolean indicating whether this role is an aggregation,
-    * i.e. whether the target objects are {@code removeYou}'d completely when using {@code without*} methods or {@code removeYou} on the source object
+    * i.e. whether the target objects are {@code removeYou}'d completely when using {@code without*} methods or
+    * {@code removeYou} on the source object
     */
    public boolean getAggregation()
    {
@@ -227,9 +237,10 @@ public boolean getAggregation()
    /**
     * @param value
     *    a boolean indicating whether this role is an aggregation,
-    *    i.e. whether the target objects are {@code removeYou}'d completely when using {@code without*} methods or {@code removeYou} on the source object
+    *    i.e. whether the target objects are {@code removeYou}'d completely when using {@code without*} methods or
+    *    {@code removeYou} on the source object
     *
-    * @return this instance, to allow method chaining
+    * @return this
     */
    public AssocRole setAggregation(boolean value)
    {
@@ -245,7 +256,8 @@ public AssocRole setAggregation(boolean value)
    }
 
    /**
-    * @return the property style of this role
+    * @return the property style.
+    * Currently, only {@link Type#POJO}, {@link Type#BEAN} and {@link Type#JAVA_FX} are supported.
     */
    public String getPropertyStyle()
    {
@@ -254,10 +266,10 @@ public String getPropertyStyle()
 
    /**
     * @param value
-    *    the property style to use for this role.
+    *    the property style.
     *    Currently, only {@link Type#POJO}, {@link Type#BEAN} and {@link Type#JAVA_FX} are supported.
     *
-    * @return this instance, to allow method chaining
+    * @return this
     */
    public AssocRole setPropertyStyle(String value)
    {
@@ -272,6 +284,80 @@ public AssocRole setPropertyStyle(String value)
       return this;
    }
 
+   /**
+    * @return the description of this role, used for generating JavaDocs
+    *
+    * @since 1.3
+    */
+   public String getDescription()
+   {
+      return this.description;
+   }
+
+   /**
+    * @param value
+    *    the description of this role, used for generating JavaDocs
+    *
+    * @return this
+    *
+    * @since 1.3
+    */
+   public AssocRole setDescription(String value)
+   {
+      if (Objects.equals(value, this.description))
+      {
+         return this;
+      }
+
+      final String oldValue = this.description;
+      this.description = value;
+      this.firePropertyChange(PROPERTY_description, oldValue, value);
+      return this;
+   }
+
+   /**
+    * @return the lines of the description of this attribute, used for generating JavaDocs
+    *
+    * @since 1.3
+    * @deprecated for internal use only
+    */
+   @Deprecated
+   public List<String> getDescriptionLines()
+   {
+      return this.getDescription() == null ? Collections.emptyList() : Arrays.asList(this.getDescription().split("\n"));
+   }
+
+   /**
+    * @return the version when this role was introduced, used for generating JavaDocs
+    *
+    * @since 1.3
+    */
+   public String getSince()
+   {
+      return this.since;
+   }
+
+   /**
+    * @param value
+    *    the version when this role was introduced, used for generating JavaDocs
+    *
+    * @return this
+    *
+    * @since 1.3
+    */
+   public AssocRole setSince(String value)
+   {
+      if (Objects.equals(value, this.since))
+      {
+         return this;
+      }
+
+      final String oldValue = this.since;
+      this.since = value;
+      this.firePropertyChange(PROPERTY_since, oldValue, value);
+      return this;
+   }
+
    /**
     * @return a boolean indicating whether this role was modified. For internal use only.
     */
@@ -284,7 +370,7 @@ public boolean getModified()
     * @param value
     *    a boolean indicating whether this role was modified. For internal use only.
     *
-    * @return this instance, to allow method chaining
+    * @return this
     */
    public AssocRole setModified(boolean value)
    {
@@ -372,6 +458,8 @@ public String toString()
       final StringBuilder result = new StringBuilder();
       result.append(' ').append(this.getName());
       result.append(' ').append(this.getPropertyStyle());
+      result.append(' ').append(this.getDescription());
+      result.append(' ').append(this.getSince());
       return result.substring(1);
    }
 }