Author: rwhitcomb Date: Tue Sep 29 22:28:43 2015 New Revision: 1705946 URL: http://svn.apache.org/viewvc?rev=1705946&view=rev Log: PIVOT-976: Mostly add @param descriptions to Javadoc (found missing by Java 8) in eleven files, although there were some other Javadoc fixes as well (adding @return and @throws).
Many, many more Javadoc warnings left to fix. Modified: pivot/trunk/core/src/org/apache/pivot/collections/Queue.java pivot/trunk/core/src/org/apache/pivot/collections/QueueListener.java pivot/trunk/core/src/org/apache/pivot/collections/Sequence.java pivot/trunk/core/src/org/apache/pivot/collections/Set.java pivot/trunk/core/src/org/apache/pivot/collections/Stack.java pivot/trunk/core/src/org/apache/pivot/collections/StackListener.java pivot/trunk/core/src/org/apache/pivot/functional/monad/None.java pivot/trunk/core/src/org/apache/pivot/functional/monad/OptionCompanion.java pivot/trunk/core/src/org/apache/pivot/functional/monad/TryCompanion.java pivot/trunk/core/src/org/apache/pivot/util/ListenerList.java pivot/trunk/core/src/org/apache/pivot/util/concurrent/Task.java Modified: pivot/trunk/core/src/org/apache/pivot/collections/Queue.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/collections/Queue.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/collections/Queue.java (original) +++ pivot/trunk/core/src/org/apache/pivot/collections/Queue.java Tue Sep 29 22:28:43 2015 @@ -72,6 +72,7 @@ public interface Queue<T> extends Collec * Removes the item from the head of the queue and returns it. Calling this * method should have the same effect as: <code>remove(getLength() - 1, * 1);</code> + * @return The (removed) object at the head of the queue. */ public T dequeue(); @@ -80,6 +81,7 @@ public interface Queue<T> extends Collec * queue. Returns null if the queue contains no items. Will also return null * if the head item in the queue is null. <tt>isEmpty()</tt> can be used to * distinguish between these two cases. + * @return The object at the head of the queue (not removed from the queue). */ public T peek(); @@ -93,12 +95,12 @@ public interface Queue<T> extends Collec public boolean isEmpty(); /** - * Returns the length of the queue. + * @return The length of the queue. */ public int getLength(); /** - * Returns the queue listener list. + * @return The queue listener list. */ public ListenerList<QueueListener<T>> getQueueListeners(); } Modified: pivot/trunk/core/src/org/apache/pivot/collections/QueueListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/collections/QueueListener.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/collections/QueueListener.java (original) +++ pivot/trunk/core/src/org/apache/pivot/collections/QueueListener.java Tue Sep 29 22:28:43 2015 @@ -50,31 +50,31 @@ public interface QueueListener<T> { /** * Called when an item has been inserted into the tail of a queue. * - * @param queue - * @param item + * @param queue The queue that has been modified. + * @param item The item that was just added to the queue. */ public void itemEnqueued(Queue<T> queue, T item); /** * Called when an item has been removed from the head of a queue. * - * @param queue - * @param item + * @param queue The queue in question. + * @param item The item that was just removed from the head of the queue. */ public void itemDequeued(Queue<T> queue, T item); /** * Called when a queue has been cleared. * - * @param queue + * @param queue The newly cleared queue object. */ public void queueCleared(Queue<T> queue); /** * Called when a queue's comparator has changed. * - * @param queue - * @param previousComparator + * @param queue The queue that changed. + * @param previousComparator Previous value of the queue's comparator (if any). */ public void comparatorChanged(Queue<T> queue, Comparator<T> previousComparator); } Modified: pivot/trunk/core/src/org/apache/pivot/collections/Sequence.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/collections/Sequence.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/collections/Sequence.java (original) +++ pivot/trunk/core/src/org/apache/pivot/collections/Sequence.java Tue Sep 29 22:28:43 2015 @@ -268,6 +268,7 @@ public interface Sequence<T> { /** * Adds an item to a nested sequence. * + * @param <T> Type of the items in this sequence. * @param sequence The root sequence. * @param item The item to be added to the sequence. * @param path The path of the sequence to which the item should be @@ -283,6 +284,7 @@ public interface Sequence<T> { /** * Inserts an item into a nested sequence. * + * @param <T> Type of items in this sequence. * @param sequence The root sequence. * @param item The item to be inserted into the sequence. * @param path The path of the sequence into which the item should be @@ -298,6 +300,7 @@ public interface Sequence<T> { /** * Updates an item in a nested sequence. * + * @param <T> The type of items in this sequence. * @param sequence The root sequence. * @param path The path of the item to update. * @param item The item that will replace any existing value at the given @@ -326,6 +329,7 @@ public interface Sequence<T> { /** * Removes the first occurrence of an item from a nested sequence. * + * @param <T> The type of items in this sequence. * @param sequence The root sequence. * @param item The item to remove. * @return The path of the item that was removed. @@ -342,10 +346,13 @@ public interface Sequence<T> { } /** - * Removes an item from a nested sequence. + * Removes items from a nested sequence. * + * @param <T> The type of items in this sequence. * @param sequence The root sequence. - * @param path The path of the item to remove. + * @param path The path of the item(s) to remove. + * @param count The number of items to remove. + * @return The sequence of items that were removed. */ @SuppressWarnings("unchecked") public static <T> Sequence<T> remove(final Sequence<T> sequence, final Path path, int count) { @@ -369,6 +376,7 @@ public interface Sequence<T> { /** * Retrieves an item from a nested sequence. * + * @param <T> The type of items in this sequence. * @param sequence The root sequence. * @param path The path of the item to retrieve. * @return The item at the given path, or <tt>null</tt> if the path is @@ -403,10 +411,11 @@ public interface Sequence<T> { /** * Returns the path to an item in a nested sequence. * + * @param <T> The type of items in this sequence. * @param sequence The root sequence. * @param item The item to locate. * @return The path of first occurrence of the item if it exists in the - * sequence; <tt>null</tt>, otherwise. + * sequence; <tt>null</tt> otherwise. */ @SuppressWarnings("unchecked") public static <T> Path pathOf(final Sequence<T> sequence, final T item) { @@ -443,6 +452,9 @@ public interface Sequence<T> { /** * Returns an iterator that will perform a depth-first traversal of the * nested sequence. + * @param <T> The type of items in this sequence. + * @param sequence The sequence for which we are requesting an iterator. + * @return The new iterator over the sequence (depth-first order). */ public static <T> ItemIterator<T> depthFirstIterator(Sequence<T> sequence) { return new DepthFirstItemIterator<>(sequence); @@ -454,6 +466,8 @@ public interface Sequence<T> { * * @param ancestorPath The ancestor path to test. * @param descendantPath The descendant path to test. + * @return <tt>true</tt> if the second argument is a descendant of the first + * path argument, <tt>false</tt> otherwise. */ public static boolean isDescendant(Path ancestorPath, Path descendantPath) { int ancestorLength = ancestorPath.getLength(); Modified: pivot/trunk/core/src/org/apache/pivot/collections/Set.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/collections/Set.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/collections/Set.java (original) +++ pivot/trunk/core/src/org/apache/pivot/collections/Set.java Tue Sep 29 22:28:43 2015 @@ -77,7 +77,7 @@ public interface Set<E> extends Group<E> public void clear(); /** - * Returns the number of elements in the set. + * @return The number of elements in the set. */ public int getCount(); @@ -88,7 +88,7 @@ public interface Set<E> extends Group<E> public void setComparator(Comparator<E> comparator); /** - * Returns the set listener collection. + * @return The set listener list. */ public ListenerList<SetListener<E>> getSetListeners(); } Modified: pivot/trunk/core/src/org/apache/pivot/collections/Stack.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/collections/Stack.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/collections/Stack.java (original) +++ pivot/trunk/core/src/org/apache/pivot/collections/Stack.java Tue Sep 29 22:28:43 2015 @@ -71,6 +71,7 @@ public interface Stack<T> extends Collec /** * Removes the top item from the stack and returns it. * + * @return The top item from the stack (removed from it). * @throws IllegalStateException If the stack contains no items. */ public T pop(); @@ -80,6 +81,7 @@ public interface Stack<T> extends Collec * Returns null if the stack contains no items. Will also return null if the * top item in the stack is null. <tt>getLength()</tt> can be used to * distinguish between these two cases. + * @return The top item from the stack (which remains there). */ public T peek(); @@ -93,12 +95,12 @@ public interface Stack<T> extends Collec public boolean isEmpty(); /** - * Returns the stack depth. + * @return The stack depth. */ public int getDepth(); /** - * Returns the stack listener list. + * @return The stack listener list. */ public ListenerList<StackListener<T>> getStackListeners(); } Modified: pivot/trunk/core/src/org/apache/pivot/collections/StackListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/collections/StackListener.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/collections/StackListener.java (original) +++ pivot/trunk/core/src/org/apache/pivot/collections/StackListener.java Tue Sep 29 22:28:43 2015 @@ -50,31 +50,31 @@ public interface StackListener<T> { /** * Called when an item has been pushed onto a stack. * - * @param stack - * @param item + * @param stack The stack that has changed. + * @param item The newly pushed item. */ public void itemPushed(Stack<T> stack, T item); /** * Called when an item has been popped off of a stack. * - * @param stack - * @param item + * @param stack The stack that has changed. + * @param item The item newly popped from the stack. */ public void itemPopped(Stack<T> stack, T item); /** * Called when a stack has been cleared. * - * @param stack + * @param stack The newly cleared stack. */ public void stackCleared(Stack<T> stack); /** * Called when a stack's comparator has changed. * - * @param stack - * @param previousComparator + * @param stack The stack in question. + * @param previousComparator The previous comparator for this stack (if any). */ public void comparatorChanged(Stack<T> stack, Comparator<T> previousComparator); } Modified: pivot/trunk/core/src/org/apache/pivot/functional/monad/None.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/functional/monad/None.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/functional/monad/None.java (original) +++ pivot/trunk/core/src/org/apache/pivot/functional/monad/None.java Tue Sep 29 22:28:43 2015 @@ -27,6 +27,7 @@ public final class None<T> extends Optio /** * Get the static instance. + * @param <T> The type of this no-value object. * @return the static instance */ public static final <T> None<T> getInstance() { Modified: pivot/trunk/core/src/org/apache/pivot/functional/monad/OptionCompanion.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/functional/monad/OptionCompanion.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/functional/monad/OptionCompanion.java (original) +++ pivot/trunk/core/src/org/apache/pivot/functional/monad/OptionCompanion.java Tue Sep 29 22:28:43 2015 @@ -27,6 +27,7 @@ public final class OptionCompanion<T> { /** * Get the static instance. + * @param <T> The type of this companion object. * @return the static instance */ public static final <T> OptionCompanion<T> getInstance() { Modified: pivot/trunk/core/src/org/apache/pivot/functional/monad/TryCompanion.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/functional/monad/TryCompanion.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/functional/monad/TryCompanion.java (original) +++ pivot/trunk/core/src/org/apache/pivot/functional/monad/TryCompanion.java Tue Sep 29 22:28:43 2015 @@ -27,6 +27,7 @@ public final class TryCompanion<T> { /** * Get the static instance. + * @param <T> The type of this companion object. * @return the static instance */ public static final <T> TryCompanion<T> getInstance() { Modified: pivot/trunk/core/src/org/apache/pivot/util/ListenerList.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/util/ListenerList.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/util/ListenerList.java (original) +++ pivot/trunk/core/src/org/apache/pivot/util/ListenerList.java Tue Sep 29 22:28:43 2015 @@ -69,7 +69,7 @@ public abstract class ListenerList<T> im /** * Adds a listener to the list, if it has not previously been added. * - * @param listener + * @param listener New listener to add to the list. */ public void add(T listener) { if (indexOf(listener) >= 0) { @@ -88,7 +88,7 @@ public abstract class ListenerList<T> im /** * Removes a listener from the list, if it has previously been added. * - * @param listener + * @param listener The listener to remove from the list. */ public void remove(T listener) { int index = indexOf(listener); @@ -122,7 +122,7 @@ public abstract class ListenerList<T> im /** * Tests the existence of a listener in the list. * - * @param listener + * @param listener The listener to test. * @return <tt>true</tt> if the listener exists in the list; <tt>false</tt>, * otherwise. */ @@ -152,9 +152,9 @@ public abstract class ListenerList<T> im /** * Get the indexed element in the list. * - * @return - * the element at position <tt>index</tt> - * or throw an <tt>IndexOutOfBoundsException</tt> + * @param index Position of the element to retrieve. + * @return The element at position <tt>index</tt>. + * @throws IndexOutOfBoundsException if the index is out of range. */ public T get(int index) { if (index < 0 || index >= last) { Modified: pivot/trunk/core/src/org/apache/pivot/util/concurrent/Task.java URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/util/concurrent/Task.java?rev=1705946&r1=1705945&r2=1705946&view=diff ============================================================================== --- pivot/trunk/core/src/org/apache/pivot/util/concurrent/Task.java (original) +++ pivot/trunk/core/src/org/apache/pivot/util/concurrent/Task.java Tue Sep 29 22:28:43 2015 @@ -183,7 +183,7 @@ public abstract class Task<V> { } /** - * Returns the executor service used to execute this task. + * @return The executor service used to execute this task. */ public ExecutorService getExecutorService() { return executorService; @@ -223,8 +223,9 @@ public abstract class Task<V> { } /** - * Returns the timeout value for this task. + * Return the timeout value for this task. * + * @return The timeout value. * @see #setTimeout(long) */ public synchronized long getTimeout() {