You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pivot.apache.org by rw...@apache.org on 2015/09/30 00:28:43 UTC
svn commit: r1705946 - in /pivot/trunk/core/src/org/apache/pivot:
collections/ functional/monad/ util/ util/concurrent/
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() {