From 1878c49c6ed567cb5c862ade4be6f0e95daed4ba Mon Sep 17 00:00:00 2001
From: Michael Barker <mikeb01@gmail.com>
Date: Wed, 7 Mar 2018 06:35:21 +1300
Subject: [PATCH] Improve documentation #96.

---
 src/main/java/com/lmax/disruptor/EventHandler.java   | 7 ++++++-
 src/main/java/com/lmax/disruptor/EventProcessor.java | 5 ++++-
 src/main/java/com/lmax/disruptor/dsl/Disruptor.java  | 4 ++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/lmax/disruptor/EventHandler.java b/src/main/java/com/lmax/disruptor/EventHandler.java
index 27bc478b2..ceacee25a 100644
--- a/src/main/java/com/lmax/disruptor/EventHandler.java
+++ b/src/main/java/com/lmax/disruptor/EventHandler.java
@@ -24,7 +24,12 @@
 public interface EventHandler<T>
 {
     /**
-     * Called when a publisher has published an event to the {@link RingBuffer}
+     * Called when a publisher has published an event to the {@link RingBuffer}.  The {@link BatchEventProcessor} will
+     * read messages from the {@link RingBuffer} in batches, where a batch is all of the events available to be
+     * processed without having to wait for any new event to arrive.  This can be useful for event handlers that need
+     * to do slower operations like I/O as they can group together the data from multiple events into a single
+     * operation.  Implementations should ensure that the operation is always performed when endOfBatch is true as
+     * the time between that message an the next one is inderminate.
      *
      * @param event      published to the {@link RingBuffer}
      * @param sequence   of the event being processed
diff --git a/src/main/java/com/lmax/disruptor/EventProcessor.java b/src/main/java/com/lmax/disruptor/EventProcessor.java
index 858689e64..eb2208ff4 100644
--- a/src/main/java/com/lmax/disruptor/EventProcessor.java
+++ b/src/main/java/com/lmax/disruptor/EventProcessor.java
@@ -16,7 +16,10 @@
 package com.lmax.disruptor;
 
 /**
- * EventProcessors waitFor events to become available for consumption from the {@link RingBuffer}
+ * An EventProcessor needs to be an implementation of a runnable that will poll for events from the {@link RingBuffer}
+ * using the appropriate wait strategy.  It is unlikely that you will need to implement this interface yourself.
+ * Look at using the {@link EventHandler} interface along with the pre-supplied BatchEventProcessor in the first
+ * instance.
  * <p>
  * An EventProcessor will generally be associated with a Thread for execution.
  */
diff --git a/src/main/java/com/lmax/disruptor/dsl/Disruptor.java b/src/main/java/com/lmax/disruptor/dsl/Disruptor.java
index 2bcf9770e..3ab8b39e6 100644
--- a/src/main/java/com/lmax/disruptor/dsl/Disruptor.java
+++ b/src/main/java/com/lmax/disruptor/dsl/Disruptor.java
@@ -155,6 +155,8 @@ private Disruptor(final RingBuffer<T> ringBuffer, final Executor executor)
      * process events before handler <code>B</code>:</p>
      * <pre><code>dw.handleEventsWith(A).then(B);</code></pre>
      *
+     * <p>This call is additive, but generally should only be called once when setting up the Disruptor instance</p>
+     *
      * @param handlers the event handlers that will process events.
      * @return a {@link EventHandlerGroup} that can be used to chain dependencies.
      */
@@ -178,6 +180,8 @@ public final EventHandlerGroup<T> handleEventsWith(final EventHandler<? super T>
      * {@link EventHandlerGroup#handleEventsWith(EventProcessorFactory...)} and {@link EventHandlerGroup#then(EventProcessorFactory...)}
      * which do have barrier sequences to provide.</p>
      *
+     * <p>This call is additive, but generally should only be called once when setting up the Disruptor instance</p>
+     *
      * @param eventProcessorFactories the event processor factories to use to create the event processors that will process events.
      * @return a {@link EventHandlerGroup} that can be used to chain dependencies.
      */