Fix javadoc (#136)

Author: wsargent

logback-classic/src/main/java/com/tersesystems/logback/classic/StartTime.java

@@ -14,20 +14,24 @@
 import ch.qos.logback.core.Context;
 import ch.qos.logback.core.spi.ContextAware;
 import com.tersesystems.logback.core.ComponentContainer;
+
 import java.time.Instant;
 import java.util.Iterator;
 import java.util.Optional;
+
 import org.slf4j.Marker;
 
-/** This class pulls an Instant from a StartTimeSupplier. */
+/**
+ * This class pulls an Instant from a StartTimeSupplier.
+ */
 public final class StartTime {
 
   /**
-   * Returns an start time from the event, then marker, then finally if not found will use the
+   * Returns a start time from the event, then marker, then finally if not found will use the
    * event's timestamp as the marker.
    *
    * @param context the logging context
-   * @param event the logging event event
+   * @param event   the logging event
    * @return an instant representing the start time.
    */
   public static Instant from(Context context, ILoggingEvent event) {
@@ -37,6 +41,10 @@ public static Instant from(Context context, ILoggingEvent event) {
   /**
    * Pulls a start time from the logging event, looking for the supplier on the event first, and
    * then looking for a StartTimeMarker.
+   *
+   * @param context the logback context
+   * @param event the event
+   * @return an optional start time, using both a container and marker as possible sources.
    */
   public static Optional<Instant> fromOptional(Context context, ILoggingEvent event) {
     if (event instanceof ComponentContainer) {
@@ -48,7 +56,12 @@ public static Optional<Instant> fromOptional(Context context, ILoggingEvent even
     return fromMarker(context, event.getMarker());
   }
 
-  /** Looks for a StartTimeMarker in the marker and in all of the children of the marker. */
+  /**
+   * Looks for a StartTimeMarker in the marker and in all the children of the marker.
+   * @param context the logback context
+   * @param m the logback marker
+   * @return an optional start time.
+   */
   public static Optional<Instant> fromMarker(Context context, Marker m) {
     if (m instanceof StartTimeSupplier) {
       StartTimeSupplier supplier = ((StartTimeSupplier) m);

logback-ringbuffer/src/main/java/com/tersesystems/logback/ringbuffer/RingBuffer.java

@@ -10,10 +10,10 @@ public interface RingBuffer<T> {
   interface Supplier<T> {
     /**
      * This method will return the next value to be written to the queue. As such the queue
-     * implementations are commited to insert the value once the call is made.
+     * implementations are committed to insert the value once the call is made.
      *
      * <p>Users should be aware that underlying queue implementations may upfront claim parts of the
-     * queue for batch operations and this will effect the view on the queue from the supplier
+     * queue for batch operations and this will affect the view on the queue from the supplier
      * method. In particular size and any offer methods may take the view that the full batch has
      * already happened.
      *
@@ -51,8 +51,6 @@ interface WaitStrategy {
      * This method can implement static or dynamic backoff. Dynamic backoff will rely on the counter
      * for estimating how long the caller has been idling. The expected usage is:
      *
-     * <p>
-     *
      * <pre>
      * <code>
      * int ic = 0;
@@ -172,8 +170,6 @@ interface ExitCondition {
    * Remove up to <i>limit</i> elements from the queue and hand to consume. This should be
    * semantically similar to:
    *
-   * <p>
-   *
    * <pre>{@code
    * M m;
    * int i = 0;
@@ -189,6 +185,8 @@ interface ExitCondition {
    * <p><b>WARNING</b>: Explicit assumptions are made with regards to {@link Consumer#accept} make
    * sure you have read and understood these before using this method.
    *
+   * @param c     the consumer
+   * @param limit the limit
    * @return the number of polled elements
    * @throws IllegalArgumentException c is {@code null}
    * @throws IllegalArgumentException if limit is negative
@@ -198,8 +196,6 @@ interface ExitCondition {
   /**
    * Stuff the queue with up to <i>limit</i> elements from the supplier. Semantically similar to:
    *
-   * <p>
-   *
    * <pre>{@code
    * for(int i=0; i < limit && relaxedOffer(s.get()); i++);
    * }</pre>
@@ -210,6 +206,8 @@ interface ExitCondition {
    * <p><b>WARNING</b>: Explicit assumptions are made with regards to {@link Supplier#get} make sure
    * you have read and understood these before using this method.
    *
+   * @param s     the supplier
+   * @param limit the limit
    * @return the number of offered elements
    * @throws IllegalArgumentException s is {@code null}
    * @throws IllegalArgumentException if limit is negative
@@ -233,6 +231,7 @@ interface ExitCondition {
    * <p><b>WARNING</b>: Explicit assumptions are made with regards to {@link Consumer#accept} make
    * sure you have read and understood these before using this method.
    *
+   * @param c the consumer
    * @return the number of polled elements
    * @throws IllegalArgumentException c is {@code null}
    */
@@ -253,6 +252,7 @@ interface ExitCondition {
    * <p><b>WARNING</b>: Explicit assumptions are made with regards to {@link Supplier#get} make sure
    * you have read and understood these before using this method.
    *
+   * @param s the supplier
    * @return the number of offered elements
    * @throws IllegalArgumentException s is {@code null}
    */
@@ -261,8 +261,6 @@ interface ExitCondition {
   /**
    * Remove elements from the queue and hand to consume forever. Semantically similar to:
    *
-   * <p>
-   *
    * <pre>
    *  int idleCounter = 0;
    *  while (exit.keepRunning()) {
@@ -281,15 +279,16 @@ interface ExitCondition {
    * <p><b>WARNING</b>: Explicit assumptions are made with regards to {@link Consumer#accept} make
    * sure you have read and understood these before using this method.
    *
+   * @param c    the consumer
+   * @param wait the wait strategy
+   * @param exit the exit condition
    * @throws IllegalArgumentException c OR wait OR exit are {@code null}
    */
   void drain(Consumer<T> c, WaitStrategy wait, ExitCondition exit);
 
   /**
    * Stuff the queue with elements from the supplier forever. Semantically similar to:
    *
-   * <p>
-   *
    * <pre>
    * <code>
    *  int idleCounter = 0;
@@ -311,6 +310,9 @@ interface ExitCondition {
    * <p><b>WARNING</b>: Explicit assumptions are made with regards to {@link Supplier#get} make sure
    * you have read and understood these before using this method.
    *
+   * @param s    the supplier
+   * @param wait the wait strategy
+   * @param exit the exit condition
    * @throws IllegalArgumentException s OR wait OR exit are {@code null}
    */
   void fill(Supplier<T> s, WaitStrategy wait, ExitCondition exit);