Documentation improvement for MT worker verticles

Applies the doc changes discussed in #2431:

- DeploymentOptions.setMultiThreaded Javadoc
- alternative to MT worker verticles (deploy as many as instances as MT worker pool size)

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

src/main/asciidoc/dataobjects.adoc

@@ -380,7 +380,11 @@ Sets the value of max worker execute time, in link.
 Set the time unit of <code>maxWorkerExecuteTime</code>
 +++
 |[[multiThreaded]]`@multiThreaded`|`Boolean`|+++
-Set whether the verticle(s) should be deployed as a multi-threaded worker verticle
+Set whether the verticle(s) should be deployed as a multi-threaded worker verticle.
+ <p>
+ <strong>WARNING</strong>: Multi-threaded worker verticles are an advanced feature and most applications will have no need for them.
+ Because of the concurrency in these verticles you have to be very careful to keep the verticle in a consistent state
+ using standard Java techniques for multi-threaded programming.
 +++
 |[[worker]]`@worker`|`Boolean`|+++
 Set whether the verticle(s) should be deployed as a worker verticle

src/main/asciidoc/index.adoc

@@ -476,10 +476,32 @@ different threads at different times.
 A multi-threaded worker verticle is just like a normal worker verticle but it *can* be executed concurrently by
 different threads.
 
-WARNING: Multi-threaded worker verticles are an advanced feature and most applications will have no need for them.
+CAUTION: Multi-threaded worker verticles are an advanced feature and most applications will have no need for them.
+
 Because of the concurrency in these verticles you have to be very careful to keep the verticle in a consistent state
 using standard Java techniques for multi-threaded programming.
 
+Multi-threaded worker verticles were designed and are intended for the sole use of consuming `EventBus` messages in parallel.
+
+WARNING: Vert.x clients and servers (TCP, HTTP, ...etc) cannot be created in a multi-threaded worker verticle.
+Should you incidentally try, an exception will be thrown.
+
+Essentially, multi-threaded worker verticles simply avoid the user from deploying as much instances of a worker verticle as the number of threads in a worker pool.
+So you could for example provide a worker pool name/size in {@link io.vertx.core.DeploymentOptions} and set the number of instances accordingly:
+
+[source,$lang]
+----
+{@link examples.CoreExamples#multiThreadedWorkerVerticleAlternative}
+----
+
+Alternatively, you could create a regular verticle and wrap you blocking code with `executeBlocking` in parallel mode (`ordered` set to `false`):
+
+[source,$lang]
+----
+{@link examples.CoreExamples#multiThreadedWorkerVerticleAlternative2}
+----
+
+
 === Deploying verticles programmatically
 
 You can deploy a verticle using one of the {@link io.vertx.core.Vertx#deployVerticle} method, specifying a verticle

src/main/java/examples/CoreExamples.java

@@ -187,6 +187,26 @@ public class CoreExamples {
     vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options);
   }
 
+  public void multiThreadedWorkerVerticleAlternative(Vertx vertx) {
+    DeploymentOptions options = new DeploymentOptions()
+      .setWorker(true)
+      .setInstances(5) // matches the worker pool size below
+      .setWorkerPoolName("the-specific-pool")
+      .setWorkerPoolSize(5);
+    vertx.deployVerticle("com.mycompany.MyOrderProcessorVerticle", options);
+  }
+
+  public void multiThreadedWorkerVerticleAlternative2(Vertx vertx, String someresult) {
+    vertx.eventBus().consumer("foo", msg -> {
+      vertx.executeBlocking(fut -> {
+        // Invoke blocking code with received message data
+        fut.complete(someresult);
+      }, false, ar -> { // ordered == false
+        // Handle result, e.g. reply to the message
+      });
+    });
+  }
+
   public void example8(Vertx vertx) {
 
     Verticle myVerticle = new MyVerticle();

src/main/java/io/vertx/core/DeploymentOptions.java

@@ -168,7 +168,11 @@ public class DeploymentOptions {
   }
 
   /**
-   * Set whether the verticle(s) should be deployed as a multi-threaded worker verticle
+   * Set whether the verticle(s) should be deployed as a multi-threaded worker verticle.
+   * <p>
+   * <strong>WARNING</strong>: Multi-threaded worker verticles are an advanced feature and most applications will have no need for them.
+   * Because of the concurrency in these verticles you have to be very careful to keep the verticle in a consistent state
+   * using standard Java techniques for multi-threaded programming.
    *
    * @param multiThreaded true for multi-threaded worker, false otherwise
    * @return a reference to this, so the API can be used fluently