Added JavaScript api docs to the build

.travis.yml

@@ -16,11 +16,17 @@ jobs:
     script:
     - cd node-support && npm test && cd -
     - cd samples/js-shopping-cart && npm test && cd -
+
   - name: sbt tests
-    before_script:
-    - sbt update
-    script:
-    - sbt 'set concurrentRestrictions in Global += Tags.limitAll(1)' test docs/paradox
+    before_script: sbt update
+    script: sbt 'set concurrentRestrictions in Global += Tags.limitAll(1)' test
+
+  - name: docs tests
+    before_script: cd node-support && npm install && cd -
+    script: sbt 'set concurrentRestrictions in Global += Tags.limitAll(1)' docs/paradox
+
+
+
   - stage: TCK
     name: Run TCK against reference implementation
     before_script:
@@ -32,7 +38,8 @@ jobs:
 
   - stage: Deploy
     name: Deploy documentation to cloudstate.io
-    if: branch = master
+    if: branch = master AND type = push
+    before_script: cd node-support && npm install && cd -
     script: sbt docs/paradox
     deploy:
       provider: pages

build.sbt

@@ -95,9 +95,20 @@ lazy val docs = (project in file("docs"))
     paradoxTheme := Some(builtinParadoxTheme("generic")),
     mappings in (Compile, paradox) ++= {
       val javaApiDocs = (doc in (`java-support`, Compile)).value
+
+      // Run the npm docs build
+      val nodeSupportDir = (baseDirectory in ThisBuild).value / "node-support"
+      import sys.process._
+      val rc = Process("npm run jsdoc", nodeSupportDir).run(streams.value.log).exitValue()
+      if (rc != 0) sys.error(s"jsdoc failed with return code $rc")
+      val javaScriptApiDocs = nodeSupportDir / "apidocs"
+
       ((javaApiDocs ** "*") pair Path.relativeTo(javaApiDocs)).map {
         case (file, path) => file -> s"user/lang/java/api/$path"
-      }
+      } ++
+        ((javaScriptApiDocs ** "*") pair Path.relativeTo(javaScriptApiDocs)).map {
+          case (file, path) => file -> s"user/lang/javascript/api/$path"
+        }
     }
   )
 
@@ -488,6 +499,9 @@ lazy val `java-support` = (project in file("java-support"))
       val javaSourceDir = (javaSource in Compile).value.getAbsolutePath
       (sources in (Compile, doc)).value.filter(_.getAbsolutePath.startsWith(javaSourceDir))
     },
+    // javadoc (I think java 9 onwards) refuses to compile javadocs if it can't compile the entire source path.
+    // but since we have java files depending on Scala files, we need to include ourselves on the classpath.
+    dependencyClasspath in (Compile, doc) := (fullClasspath in Compile).value,
 
     libraryDependencies ++= Seq(
       // Remove these explicit gRPC/netty dependencies once akka-grpc 0.7.1 is released and we've upgraded to using that

docs/src/main/paradox/user/lang/javascript/api.md

@@ -0,0 +1,3 @@
+# JavaScript API docs
+
+The JavaScript API docs can be found [here](api/index.html).

docs/src/main/paradox/user/lang/javascript/index.md

@@ -14,5 +14,6 @@
 * [Conflict-free Replicated Data Types](crdt.md)
 * [Forwarding and effects](effects.md)
 * [Serialization](serialization.md)
+* [API docs](api.md)
 
 @@@

java-support/src/main/java/io/cloudstate/javasupport/ClientActionContext.java

@@ -2,7 +2,7 @@
 
 /**
  * Context that provides client actions, which include failing and forwarding.
- * <p/>
+ * <p>
  * These contexts are typically made available in response to commands.
  */
 public interface ClientActionContext extends Context {
@@ -15,10 +15,10 @@ public interface ClientActionContext extends Context {
 
     /**
      * Instruct the proxy to forward handling of this command to another entity served by this stateful function.
-     * <p/>
+     * <p>
      * The command will be forwarded after successful completion of handling this command, including any persistence
      * that this command does.
-     * <p/>
+     * <p>
      * {@link ServiceCall} instances can be created using the {@link ServiceCallFactory} obtained from any (including
      * this) contexts {@link Context#serviceCallFactory()} method.
      *

java-support/src/main/java/io/cloudstate/javasupport/CloudState.java

@@ -75,7 +75,7 @@ public CloudState preferScalaProtobufs() {
 
     /**
      * Register an annotated event sourced entity.
-     * <p/>
+     * <p>
      * The entity class must be annotated with {@link io.cloudstate.javasupport.eventsourced.EventSourcedEntity}.
      *
      * @param entityClass The entity class.
@@ -113,7 +113,7 @@ public CloudState registerEventSourcedEntity(Class<?> entityClass, Descriptors.S
 
     /**
      * Register an event sourced entity factor.
-     * <p/>
+     * <p>
      * This is a low level API intended for custom (eg, non reflection based) mechanisms for implementing the entity.
      *
      * @param factory The event sourced factory.
@@ -134,7 +134,7 @@ public CloudState registerEventSourcedEntity(EventSourcedEntityFactory factory,
 
     /**
      * Register an annotated CRDT entity.
-     * <p/>
+     * <p>
      * The entity class must be annotated with {@link io.cloudstate.javasupport.crdt.CrdtEntity}.
      *
      * @param entityClass The entity class.
@@ -161,7 +161,7 @@ public CloudState registerCrdtEntity(Class<?> entityClass, Descriptors.ServiceDe
 
     /**
      * Register an CRDt entity factory.
-     * <p/>
+     * <p>
      * This is a low level API intended for custom (eg, non reflection based) mechanisms for implementing the entity.
      *
      * @param factory The CRDT factory.

java-support/src/main/java/io/cloudstate/javasupport/EffectContext.java

@@ -7,10 +7,10 @@ public interface EffectContext extends Context {
 
     /**
      * Invoke the referenced service call as an effect once this action is completed.
-     * <p/>
+     * <p>
      * The effect will be performed asynchronously, ie, the proxy won't wait for the effect to finish before sending
      * the reply.
-     * <p/>
+     * <p>
      * {@link ServiceCall} instances can be created using the {@link ServiceCallFactory} obtained from any (including
      * this) contexts {@link Context#serviceCallFactory()} method.
      *
@@ -22,7 +22,7 @@ default void effect(ServiceCall effect) {
 
     /**
      * Invoke the referenced service call as an effect once this action is completed.
-     * <p/>
+     * <p>
      * {@link ServiceCall} instances can be created using the {@link ServiceCallFactory} obtained from any (including
      * this) contexts {@link Context#serviceCallFactory()} method.
      *

java-support/src/main/java/io/cloudstate/javasupport/EntityId.java

@@ -10,10 +10,10 @@
 
 /**
  * Annotation used to indicate that the annotated parameter accepts an entity id.
- * <p/>
+ * <p>
  * This parameter may appear on handler methods and constructors for any class that provides behavior for stateful
  * service entity.
- * <p/>
+ * <p>
  * The type of the parameter must be {@link String}.
  */
 @CloudStateAnnotation

java-support/src/main/java/io/cloudstate/javasupport/ServiceCallFactory.java

@@ -2,8 +2,8 @@
 
 /**
  * A service call factory.
- * <p/>
- * This is used to create {@link ServiceCall's} that can be passed to {@link EffectContext#effect(ServiceCall)} and
+ * <p>
+ * This is used to create {@link ServiceCall}'s that can be passed to {@link EffectContext#effect(ServiceCall)} and
  * {@link ClientActionContext#forward(ServiceCall)} f}.
  */
 public interface ServiceCallFactory {

java-support/src/main/java/io/cloudstate/javasupport/crdt/CommandContext.java

@@ -7,7 +7,7 @@
 
 /**
  * Context for handling a command.
- * </p>
+ * <p>
  * This may be passed to any {@link CommandHandler} annotated element.
  */
 public interface CommandContext extends CrdtContext, CrdtFactory, EffectContext, ClientActionContext {
@@ -21,7 +21,7 @@ public interface CommandContext extends CrdtContext, CrdtFactory, EffectContext,
 
     /**
      * The name of the command.
-     * </p>
+     * <p>
      * Corresponds to the name of the rpc call in the protobuf definition.
      *
      * @return The name of the command.
@@ -30,7 +30,7 @@ public interface CommandContext extends CrdtContext, CrdtFactory, EffectContext,
 
     /**
      * Delete the CRDT.
-     * </p>
+     * <p>
      * When a CRDT is deleted, it may not be created again. Additionally, CRDT deletion results in tombstones that
      * get accumulated for the life of the cluster. If you expect to delete CRDTs frequently, it's recommended that you
      * store them in a single or sharded {@link ORMap}, rather than individual CRDTs.

java-support/src/main/java/io/cloudstate/javasupport/crdt/CommandHandler.java

@@ -9,13 +9,13 @@
 
 /**
  * Marks a method as a command handler.
- * <p/>
+ * <p>
  * This method will be invoked whenever the service call with name that matches this command handlers name is invoked.
- * <p/>
+ * <p>
  * The method may take the command object as a parameter, its type must match the gRPC service input type.
- * <p/>
+ * <p>
  * The return type of the method must match the gRPC services output type.
- * <p/>
+ * <p>
  * The method may also take a {@link CommandContext}, and/or a {@link io.cloudstate.javasupport.EntityId} annotated
  * {@link String} parameter.
  */
@@ -26,7 +26,7 @@
 
     /**
      * The name of the command to handle.
-     * <p/>
+     * <p>
      * If not specified, the name of the method will be used as the command name, with the first letter capitalized to
      * match the gRPC convention of capitalizing rpc method names.
      *

java-support/src/main/java/io/cloudstate/javasupport/crdt/CrdtCreationContext.java

@@ -2,7 +2,7 @@
 
 /**
  * Context for CRDT creation.
- * <p/>
+ * <p>
  * This is available for injection into the constructor of a CRDT.
  */
 public interface CrdtCreationContext extends CrdtContext, CrdtFactory {

java-support/src/main/java/io/cloudstate/javasupport/crdt/CrdtEntity.java

@@ -9,13 +9,13 @@
 
 /**
  * A CRDT backed entity.
- * <p/>
+ * <p>
  * CRDT entities store their state in a subclass {@link Crdt}. These may be created using a {@link CrdtFactory}, which
  * can be injected into the constructor or as a parameter to any {@link CommandHandler} annotated method.
- * <p/>
+ * <p>
  * Only one CRDT may be created, it is important that before creating a CRDT, the entity should check whether the CRDT
  * has already been created, for example, it may have been created on another node and replicated to this node. To
- * check, either use the {@link CrdtContext#state()} method, which can be injected into the constructor or any
+ * check, either use the {@link CrdtContext#state(Class)} method, which can be injected into the constructor or any
  * {@link CommandHandler} method, or have an instance of the CRDT wrapped in {@link java.util.Optional} injected into
  * the constructor or command handler methods.
  */

java-support/src/main/java/io/cloudstate/javasupport/crdt/CrdtEntityFactory.java

@@ -2,13 +2,13 @@
 
 /**
  * Low level interface for handling commands for CRDTs.
- * <p/>
+ * <p>
  * Generally, this should not be used, rather, a {@link CrdtEntity} annotated class should be used.
  */
 public interface CrdtEntityFactory {
     /**
      * Create a CRDT entity handler for the given context.
-     * <p/>
+     * <p>
      * This will be invoked each time a new CRDT entity stream from the proxy is established, for handling commands\
      * for a single CRDT.
      *

java-support/src/main/java/io/cloudstate/javasupport/crdt/CrdtEntityHandler.java

@@ -6,9 +6,9 @@
 
 /**
  * Low level interface for handling CRDT commands.
- * <p/>
+ * <p>
  * These are instantiated by a {@link CrdtEntityFactory}.
- * <p/>
+ * <p>
  * Generally, this should not be used, rather, a {@link CrdtEntity} annotated class should be used.
  */
 public interface CrdtEntityHandler {

java-support/src/main/java/io/cloudstate/javasupport/crdt/CrdtFactory.java

@@ -2,9 +2,9 @@
 
 /**
  * Factory for creating CRDTs.
- * <p/>
+ * <p>
  * This is used both by CRDT contexts that allow creating CRDTs, as well as by CRDTs that allow nesting other CRDTs.
- * <p/>
+ * <p>
  * CRDTs may only be created by a supplied CRDT factory, CRDTs created any other way will not be known by the
  * library and so won't have their deltas synced to and from the proxy.
  */

java-support/src/main/java/io/cloudstate/javasupport/crdt/Flag.java

@@ -2,7 +2,7 @@
 
 /**
  * A flag CRDT.
- * <p/>
+ * <p>
  * A flag is a boolean value that starts out as <code>false</code>, and once set to <code>true</code>, stays
  * <code>true</code>, it cannot be set back to <code>false</code>.
  */

java-support/src/main/java/io/cloudstate/javasupport/crdt/GCounter.java

@@ -2,7 +2,7 @@
 
 /**
  * A Grow-only Counter.
- * <p/>
+ * <p>
  * A Grow-only Counter can be incremented, but can't be decremented.
  */
 public interface GCounter extends Crdt {

java-support/src/main/java/io/cloudstate/javasupport/crdt/GSet.java

@@ -4,9 +4,9 @@
 
 /**
  * A Grow-only Set.
- * <p/>
+ * <p>
  * A Grow-only Set can have elements added to it, but cannot have elements removed from it.
- * <p/>
+ * <p>
  * Care needs to be taken to ensure that the serialized value of elements in the set is stable. For example, if using
  * protobufs, the serialized value of any maps contain in the protobuf is not stable, and can yield a different set of
  * bytes for the same logically equal element. Hence maps, should be avoided. Additionally, some changes in protobuf

java-support/src/main/java/io/cloudstate/javasupport/crdt/LWWRegister.java

@@ -2,10 +2,10 @@
 
 /**
  * A Last-Write-Wins Register.
- * <p/>
+ * <p>
  * This uses a clock value to determine which of two concurrent writes should win. When both clock values are the same,
  * an ordering defined over the node addresses is used to break the tie.
- * <p/>
+ * <p>
  * By default, the clock used is the clock of the node that set the value. This can be affected by clock skew, which
  * means two successive writes delegated to two separate nodes could result in the first one winning. This can be
  * avoided by using a custom clock with a domain specific clock value, if such a causally ordered value is available.
@@ -54,16 +54,16 @@ enum Clock {
 
         /**
          * A reverse clock, based on the system clock.
-         * <p/>
+         * <p>
          * Using this effectively achieves First-Write-Wins semantics.
-         * <p/>
+         * <p>
          * This is susceptible to the same clock skew problems as the default clock.
          */
         REVERSE,
 
         /**
          * A custom clock.
-         * <p/>
+         * <p>
          * The custom clock value is passed by using the <code>customClockValue</code> parameter on the
          * {@link LWWRegister#set(Object, Clock, long)} method. The value should be a domain specific monotonically
          * increasing value. For example, if the source of the value for this register is a single device, that device
@@ -74,11 +74,11 @@ enum Clock {
 
         /**
          * A custom clock, that automatically increments the custom value if the local clock value is greater than it.
-         * <p/>
+         * <p>
          * This is like {@link Clock#CUSTOM}, however if when performing the update in the proxy, it's found that the
          * clock value of the register is greater than the specified clock value for the update, the proxy will instead
          * use the current clock value of the register plus one.
-         * <p/>
+         * <p>
          * This can guarantee that updates done on the same node will be causally ordered (addressing problems caused by
          * the system clock being adjusted), but will not guarantee causal ordering for updates on different nodes,
          * since it's possible that an update on a different node has not yet been replicated to this node.

java-support/src/main/java/io/cloudstate/javasupport/crdt/LWWRegisterMap.java

@@ -4,7 +4,7 @@
 
 /**
  * Convenience wrapper class for {@link ORMap} that uses {@link LWWRegister}'s for values.
- * <p/>
+ * <p>
  * This is useful as it allows the map to be used more idiomatically, with plain {@link Map#get(Object)} and
  * {@link Map#put(Object, Object)} calls for values.
  *