#48 add some javadocs to internal methods for clarity

nakadi-producer/src/main/java/org/zalando/nakadiproducer/transmission/impl/EventBatcher.java

@@ -30,6 +30,12 @@ public EventBatcher(ObjectMapper objectMapper, Consumer<List<BatchItem>> publish
         this.aggregatedBatchSize = 0;
     }
 
+    /**
+     * Pushes one event to be published. It will be either published right now, or with some other events,
+     * latest when calling {@link #finish()}.
+     * @param eventLogEntry The event log entry for this event.
+     * @param nakadiEvent The Nakadi form of the event.
+     */
     public void pushEvent(EventLog eventLogEntry, NakadiEvent nakadiEvent) {
         long eventSize;
 
@@ -53,6 +59,9 @@ public void pushEvent(EventLog eventLogEntry, NakadiEvent nakadiEvent) {
         aggregatedBatchSize += eventSize;
     }
 
+    /**
+     * Publishes all events which were pushed and not yet published.
+     */
     public void finish() {
         if (!batch.isEmpty()) {
             this.publisher.accept(batch);

nakadi-producer/src/main/java/org/zalando/nakadiproducer/transmission/impl/EventTransmissionService.java

@@ -73,6 +73,10 @@ public void sendEvents(Collection<EventLog> events) {
         batcher.finish();
     }
 
+    /**
+     * Publishes a list of events.
+     * All of the events in this list need to be destined for the same event type.
+     */
     private void publishBatch(List<BatchItem> batch) {
         try {
             this.tryToPublishBatch(batch);
@@ -81,6 +85,10 @@ private void publishBatch(List<BatchItem> batch) {
         }
     }
 
+    /**
+     * Tries to publish a set of events (all of which need to belong to the same event type).
+     * The successful ones will be deleted from the database.
+     */
     private void tryToPublishBatch(List<BatchItem> batch) throws Exception {
         Stream<EventLog> successfulEvents;
         String eventType = batch.get(0).getEventLogEntry().getEventType();