Add docs for enum types (#96)

README.md

@@ -21,7 +21,7 @@ repositories {
 }
 
 dependencies {
-    implementation("app.photofox.vips-ffm:vips-ffm-core:0.5.13")
+    implementation("app.photofox.vips-ffm:vips-ffm-core:0.5.14")
 }
 ```
 When running your project you must add `--enable-native-access=ALL-UNNAMED` to your JVM runtime arguments. If you

core/build.gradle.kts

@@ -26,7 +26,7 @@ java {
 
 tasks.withType<Javadoc> {
     this.options.overview = "../README.md"
-    (options as StandardJavadocDocletOptions).tags("optionalArg:a:\"Optional arguments:\"")
+    (options as StandardJavadocDocletOptions).tags("optionalArg:a:Optional arguments:")
 
     doLast {
         copy {

core/src/main/java/app/photofox/vipsffm/enums/VipsAccess.java

@@ -4,9 +4,24 @@
 import java.lang.Override;
 import java.lang.String;
 
+/**
+ * <p>The type of access an operation has to supply. See {@link app.photofox.vipsffm.VImage#tilecache}
+ * and {@code VipsForeign}.</p>
+ *
+ * <p>{@link VipsAccess#ACCESS_RANDOM} means requests can come in any order.</p>
+ *
+ * <p>{@link VipsAccess#ACCESS_SEQUENTIAL} means requests will be top-to-bottom, but with some
+ * amount of buffering behind the read point for small non-local accesses.</p>
+ */
 public enum VipsAccess implements VNamedEnum {
+  /**
+   * <p>can read anywhere</p>
+   */
   ACCESS_RANDOM("VIPS_ACCESS_RANDOM", "random", 0),
 
+  /**
+   * <p>top-to-bottom reading only, but with a small buffer</p>
+   */
   ACCESS_SEQUENTIAL("VIPS_ACCESS_SEQUENTIAL", "sequential", 1),
 
   ACCESS_SEQUENTIAL_UNBUFFERED("VIPS_ACCESS_SEQUENTIAL_UNBUFFERED", "sequential-unbuffered", 2),

core/src/main/java/app/photofox/vipsffm/enums/VipsAlign.java

@@ -4,11 +4,28 @@
 import java.lang.Override;
 import java.lang.String;
 
+/**
+ * <p>See {@link app.photofox.vipsffm.VImage#join} and so on.</p>
+ *
+ * <p>Operations like {@link app.photofox.vipsffm.VImage#join} need to be told whether to align images on the
+ * low or high coordinate edge, or centre.</p>
+ *
+ * <p>See also: {@link app.photofox.vipsffm.VImage#join}.</p>
+ */
 public enum VipsAlign implements VNamedEnum {
+  /**
+   * <p>align low coordinate edge</p>
+   */
   ALIGN_LOW("VIPS_ALIGN_LOW", "low", 0),
 
+  /**
+   * <p>align centre</p>
+   */
   ALIGN_CENTRE("VIPS_ALIGN_CENTRE", "centre", 1),
 
+  /**
+   * <p>align high coordinate edge</p>
+   */
   ALIGN_HIGH("VIPS_ALIGN_HIGH", "high", 2),
 
   ALIGN_LAST("VIPS_ALIGN_LAST", "last", 3);

core/src/main/java/app/photofox/vipsffm/enums/VipsAngle.java

@@ -4,13 +4,32 @@
 import java.lang.Override;
 import java.lang.String;
 
+/**
+ * <p>See {@link app.photofox.vipsffm.VImage#rot} and so on.</p>
+ *
+ * <p>Fixed rotate angles.</p>
+ *
+ * <p>See also: {@link app.photofox.vipsffm.VImage#rot}.</p>
+ */
 public enum VipsAngle implements VNamedEnum {
+  /**
+   * <p>no rotate</p>
+   */
   ANGLE_D0("VIPS_ANGLE_D0", "d0", 0),
 
+  /**
+   * <p>90 degrees clockwise</p>
+   */
   ANGLE_D90("VIPS_ANGLE_D90", "d90", 1),
 
+  /**
+   * <p>180 degree rotate</p>
+   */
   ANGLE_D180("VIPS_ANGLE_D180", "d180", 2),
 
+  /**
+   * <p>90 degrees anti-clockwise</p>
+   */
   ANGLE_D270("VIPS_ANGLE_D270", "d270", 3),
 
   ANGLE_LAST("VIPS_ANGLE_LAST", "last", 4);

core/src/main/java/app/photofox/vipsffm/enums/VipsAngle45.java

@@ -4,21 +4,52 @@
 import java.lang.Override;
 import java.lang.String;
 
+/**
+ * <p>See {@link app.photofox.vipsffm.VImage#rot45} and so on.</p>
+ *
+ * <p>Fixed rotate angles.</p>
+ *
+ * <p>See also: {@link app.photofox.vipsffm.VImage#rot45}.</p>
+ */
 public enum VipsAngle45 implements VNamedEnum {
+  /**
+   * <p>no rotate</p>
+   */
   ANGLE45_D0("VIPS_ANGLE45_D0", "d0", 0),
 
+  /**
+   * <p>45 degrees clockwise</p>
+   */
   ANGLE45_D45("VIPS_ANGLE45_D45", "d45", 1),
 
+  /**
+   * <p>90 degrees clockwise</p>
+   */
   ANGLE45_D90("VIPS_ANGLE45_D90", "d90", 2),
 
+  /**
+   * <p>135 degrees clockwise</p>
+   */
   ANGLE45_D135("VIPS_ANGLE45_D135", "d135", 3),
 
+  /**
+   * <p>180 degrees</p>
+   */
   ANGLE45_D180("VIPS_ANGLE45_D180", "d180", 4),
 
+  /**
+   * <p>135 degrees anti-clockwise</p>
+   */
   ANGLE45_D225("VIPS_ANGLE45_D225", "d225", 5),
 
+  /**
+   * <p>90 degrees anti-clockwise</p>
+   */
   ANGLE45_D270("VIPS_ANGLE45_D270", "d270", 6),
 
+  /**
+   * <p>45 degrees anti-clockwise</p>
+   */
   ANGLE45_D315("VIPS_ANGLE45_D315", "d315", 7),
 
   ANGLE45_LAST("VIPS_ANGLE45_LAST", "last", 8);

core/src/main/java/app/photofox/vipsffm/enums/VipsBandFormat.java

@@ -4,27 +4,66 @@
 import java.lang.Override;
 import java.lang.String;
 
+/**
+ * <p>The format used for each band element.</p>
+ *
+ * <p>Each corresponds to a native C type for the current machine. For example,
+ * {@link VipsBandFormat#FORMAT_USHORT} is &lt;type&gt;unsigned short&lt;/type&gt;.</p>
+ */
 public enum VipsBandFormat implements VNamedEnum {
+  /**
+   * <p>invalid setting</p>
+   */
   FORMAT_NOTSET("VIPS_FORMAT_NOTSET", "notset", -1),
 
+  /**
+   * <p>unsigned char format</p>
+   */
   FORMAT_UCHAR("VIPS_FORMAT_UCHAR", "uchar", 0),
 
+  /**
+   * <p>char format</p>
+   */
   FORMAT_CHAR("VIPS_FORMAT_CHAR", "char", 1),
 
+  /**
+   * <p>unsigned short format</p>
+   */
   FORMAT_USHORT("VIPS_FORMAT_USHORT", "ushort", 2),
 
+  /**
+   * <p>short format</p>
+   */
   FORMAT_SHORT("VIPS_FORMAT_SHORT", "short", 3),
 
+  /**
+   * <p>unsigned int format</p>
+   */
   FORMAT_UINT("VIPS_FORMAT_UINT", "uint", 4),
 
+  /**
+   * <p>int format</p>
+   */
   FORMAT_INT("VIPS_FORMAT_INT", "int", 5),
 
+  /**
+   * <p>float format</p>
+   */
   FORMAT_FLOAT("VIPS_FORMAT_FLOAT", "float", 6),
 
+  /**
+   * <p>complex (two floats) format</p>
+   */
   FORMAT_COMPLEX("VIPS_FORMAT_COMPLEX", "complex", 7),
 
+  /**
+   * <p>double float format</p>
+   */
   FORMAT_DOUBLE("VIPS_FORMAT_DOUBLE", "double", 8),
 
+  /**
+   * <p>double complex (two double) format</p>
+   */
   FORMAT_DPCOMPLEX("VIPS_FORMAT_DPCOMPLEX", "dpcomplex", 9),
 
   FORMAT_LAST("VIPS_FORMAT_LAST", "last", 10);

core/src/main/java/app/photofox/vipsffm/enums/VipsBlendMode.java

@@ -4,55 +4,140 @@
 import java.lang.Override;
 import java.lang.String;
 
+/**
+ * <p>The various Porter-Duff and PDF blend modes. See {@link app.photofox.vipsffm.VImage#composite},
+ * for example.</p>
+ *
+ * <p>The Cairo docs have a nice explanation of all the blend modes:</p>
+ *
+ * <p>https://www.cairographics.org/operators</p>
+ *
+ * <p>The non-separable modes are not implemented.</p>
+ */
 public enum VipsBlendMode implements VNamedEnum {
+  /**
+   * <p>where the second object is drawn, the first is removed</p>
+   */
   BLEND_MODE_CLEAR("VIPS_BLEND_MODE_CLEAR", "clear", 0),
 
+  /**
+   * <p>the second object is drawn as if nothing were below</p>
+   */
   BLEND_MODE_SOURCE("VIPS_BLEND_MODE_SOURCE", "source", 1),
 
+  /**
+   * <p>the image shows what you would expect if you held two semi-transparent slides on top of each other</p>
+   */
   BLEND_MODE_OVER("VIPS_BLEND_MODE_OVER", "over", 2),
 
+  /**
+   * <p>the first object is removed completely, the second is only drawn where the first was</p>
+   */
   BLEND_MODE_IN("VIPS_BLEND_MODE_IN", "in", 3),
 
+  /**
+   * <p>the second is drawn only where the first isn't</p>
+   */
   BLEND_MODE_OUT("VIPS_BLEND_MODE_OUT", "out", 4),
 
+  /**
+   * <p>this leaves the first object mostly intact, but mixes both objects in the overlapping area</p>
+   */
   BLEND_MODE_ATOP("VIPS_BLEND_MODE_ATOP", "atop", 5),
 
+  /**
+   * <p>leaves the first object untouched, the second is discarded completely</p>
+   */
   BLEND_MODE_DEST("VIPS_BLEND_MODE_DEST", "dest", 6),
 
+  /**
+   * <p>like OVER, but swaps the arguments</p>
+   */
   BLEND_MODE_DEST_OVER("VIPS_BLEND_MODE_DEST_OVER", "dest-over", 7),
 
+  /**
+   * <p>like IN, but swaps the arguments</p>
+   */
   BLEND_MODE_DEST_IN("VIPS_BLEND_MODE_DEST_IN", "dest-in", 8),
 
+  /**
+   * <p>like OUT, but swaps the arguments</p>
+   */
   BLEND_MODE_DEST_OUT("VIPS_BLEND_MODE_DEST_OUT", "dest-out", 9),
 
+  /**
+   * <p>like ATOP, but swaps the arguments</p>
+   */
   BLEND_MODE_DEST_ATOP("VIPS_BLEND_MODE_DEST_ATOP", "dest-atop", 10),
 
+  /**
+   * <p>something like a difference operator</p>
+   */
   BLEND_MODE_XOR("VIPS_BLEND_MODE_XOR", "xor", 11),
 
+  /**
+   * <p>a bit like adding the two images</p>
+   */
   BLEND_MODE_ADD("VIPS_BLEND_MODE_ADD", "add", 12),
 
+  /**
+   * <p>a bit like the darker of the two</p>
+   */
   BLEND_MODE_SATURATE("VIPS_BLEND_MODE_SATURATE", "saturate", 13),
 
+  /**
+   * <p>at least as dark as the darker of the two inputs</p>
+   */
   BLEND_MODE_MULTIPLY("VIPS_BLEND_MODE_MULTIPLY", "multiply", 14),
 
+  /**
+   * <p>at least as light as the lighter of the inputs</p>
+   */
   BLEND_MODE_SCREEN("VIPS_BLEND_MODE_SCREEN", "screen", 15),
 
+  /**
+   * <p>multiplies or screens colors, depending on the lightness</p>
+   */
   BLEND_MODE_OVERLAY("VIPS_BLEND_MODE_OVERLAY", "overlay", 16),
 
+  /**
+   * <p>the darker of each component</p>
+   */
   BLEND_MODE_DARKEN("VIPS_BLEND_MODE_DARKEN", "darken", 17),
 
+  /**
+   * <p>the lighter of each component</p>
+   */
   BLEND_MODE_LIGHTEN("VIPS_BLEND_MODE_LIGHTEN", "lighten", 18),
 
+  /**
+   * <p>brighten first by a factor second</p>
+   */
   BLEND_MODE_COLOUR_DODGE("VIPS_BLEND_MODE_COLOUR_DODGE", "colour-dodge", 19),
 
+  /**
+   * <p>darken first by a factor of second</p>
+   */
   BLEND_MODE_COLOUR_BURN("VIPS_BLEND_MODE_COLOUR_BURN", "colour-burn", 20),
 
+  /**
+   * <p>multiply or screen, depending on lightness</p>
+   */
   BLEND_MODE_HARD_LIGHT("VIPS_BLEND_MODE_HARD_LIGHT", "hard-light", 21),
 
+  /**
+   * <p>darken or lighten, depending on lightness</p>
+   */
   BLEND_MODE_SOFT_LIGHT("VIPS_BLEND_MODE_SOFT_LIGHT", "soft-light", 22),
 
+  /**
+   * <p>difference of the two</p>
+   */
   BLEND_MODE_DIFFERENCE("VIPS_BLEND_MODE_DIFFERENCE", "difference", 23),
 
+  /**
+   * <p>somewhat like DIFFERENCE, but lower-contrast</p>
+   */
   BLEND_MODE_EXCLUSION("VIPS_BLEND_MODE_EXCLUSION", "exclusion", 24),
 
   BLEND_MODE_LAST("VIPS_BLEND_MODE_LAST", "last", 25);

core/src/main/java/app/photofox/vipsffm/enums/VipsCoding.java

@@ -4,13 +4,32 @@
 import java.lang.Override;
 import java.lang.String;
 
+/**
+ * <p>How pixels are coded.</p>
+ *
+ * <p>Normally, pixels are uncoded and can be manipulated as you would expect.
+ * However some file formats code pixels for compression, and sometimes it's
+ * useful to be able to manipulate images in the coded format.</p>
+ *
+ * <p>The gaps in the numbering are historical and must be maintained. Allocate
+ * new numbers from the end.</p>
+ */
 public enum VipsCoding implements VNamedEnum {
   CODING_ERROR("VIPS_CODING_ERROR", "error", -1),
 
+  /**
+   * <p>pixels are not coded</p>
+   */
   CODING_NONE("VIPS_CODING_NONE", "none", 0),
 
+  /**
+   * <p>pixels encode 3 float CIELAB values as 4 uchar</p>
+   */
   CODING_LABQ("VIPS_CODING_LABQ", "labq", 2),
 
+  /**
+   * <p>pixels encode 3 float RGB as 4 uchar (Radiance coding)</p>
+   */
   CODING_RAD("VIPS_CODING_RAD", "rad", 6),
 
   CODING_LAST("VIPS_CODING_LAST", "last", 7);