Author: j16sdiz
Date: 2008-04-09 16:01:28 +0000 (Wed, 09 Apr 2008)
New Revision: 19114
Modified:
trunk/freenet/src/freenet/support/DoublyLinkedList.java
trunk/freenet/src/freenet/support/DoublyLinkedListImpl.java
trunk/freenet/src/freenet/support/math/BootstrappingDecayingRunningAverage.java
Log:
javadoc and style fix
Modified: trunk/freenet/src/freenet/support/DoublyLinkedList.java
===================================================================
--- trunk/freenet/src/freenet/support/DoublyLinkedList.java 2008-04-09
16:01:05 UTC (rev 19113)
+++ trunk/freenet/src/freenet/support/DoublyLinkedList.java 2008-04-09
16:01:28 UTC (rev 19114)
@@ -7,30 +7,54 @@
* @author tavin
*/
public interface DoublyLinkedList {
+ public abstract Object clone();
- public abstract Object clone();
-
+ /**
+ * List element
+ */
public interface Item {
+ /**
+ * Get next {@link Item}. May or may not return
+ * <code>null</code> if this is the last <code>Item</code>.
+ *
+ * @see DoublyLinkedList#hasNext()
+ */
Item getNext();
+ /** Set next {@link Item} */
Item setNext(Item i);
+ /**
+ * Get previous {@link Item}. May or may not return <code>null</code>
+ * if this is the first <code>Item</code>.
+ *
+ * @see DoublyLinkedList#hasNext()
+ */
Item getPrev();
+ /** Get previous {@link Item} */
Item setPrev(Item i);
- // Strictly for sanity checking
+
+ /** Return the contained list. <strong>For sanity checking
only.</strong> */
DoublyLinkedList getParent();
+ /** Set the contained list. <strong>For sanity checking
only.</strong>*/
DoublyLinkedList setParent(DoublyLinkedList l);
}
+ /** Clear this list */
void clear();
+ /** Return the size of this list */
int size();
+ /** Check if this list is empty. @return <code>true</code> if this list is
empty, <code>false</code> otherwise. */
boolean isEmpty();
+ /** Get a {@link Enumeration} of {@link DoublyLinkedList.Item}. */
Enumeration elements(); // for consistency w/ typical Java API
/**
* Returns the first item.
+ * @return the item at the head of the list, or <code>null</code> if empty
*/
Item head();
/**
* Returns the last item.
+ * @return the item at the tail of the list, or <code>null</code> if empty
*/
Item tail();
@@ -38,35 +62,64 @@
* Puts the item before the first item.
*/
void unshift(Item i);
+ /**
+ * Put all items in the specified list before the first item.
+ */
void unshift(DoublyLinkedList l);
/**
* Removes and returns the first item.
*/
Item shift();
+ /**
+ * Remove <tt>n</tt> elements from head and return them as a
<code>DoublyLinkedList</code>.
+ */
DoublyLinkedList shift(int n);
/**
* Puts the item after the last item.
*/
void push(Item i);
+ /**
+ * Puts all items in the specified list after the last item.
+ */
void push(DoublyLinkedList l);
/**
* Removes and returns the last item.
*/
Item pop();
+ /**
+ * Remove <tt>n</tt> elements from tail and return them as a
<code>DoublyLinkedList</code>.
+ */
DoublyLinkedList pop(int n);
+ /** @return <code>true</code> if <code>i</code> has next item. (ie. not
the last item); <code>false</code> otherwise */
boolean hasNext(Item i);
+ /** @return <code>true</code> if <code>i</code> has previous item. (ie.
not the first item); <code>false</code> otherwise */
boolean hasPrev(Item i);
+ /** @return next item of <code>i</code>. If this is the last element,
return <code>null</code> */
Item next(Item i);
+ /** @return previous item of <code>i</code>. If this is the first element,
return <code>null</code> */
Item prev(Item i);
-
+ /** Remove and return a element
+ * @return this item, or <code>null</code> if the item was not in the list
+ */
Item remove(Item i);
-
+ /**
+ * Inserts item <code>j</code> before item <code>i</code>.
+ */
void insertPrev(Item i, Item j);
- void insertPrev(Item i, DoublyLinkedList l);
- void insertNext(Item i, Item j);
+ /**
+ * Inserts the entire {@link DoublyLinkedList} <code>l</code> before item
<code>i</code>.
+ */
+ void insertPrev(Item i, DoublyLinkedList l);
+ /**
+ * Inserts item <code>j</code> after item <code>i</code.
+ */
+ void insertNext(Item i, Item j);
+ /**
+ * Inserts the entire {@link DoublyLinkedList} <code>l</code> after item
<code>i</code>.
+ */
void insertNext(Item i, DoublyLinkedList l);
}
Modified: trunk/freenet/src/freenet/support/DoublyLinkedListImpl.java
===================================================================
--- trunk/freenet/src/freenet/support/DoublyLinkedListImpl.java 2008-04-09
16:01:05 UTC (rev 19113)
+++ trunk/freenet/src/freenet/support/DoublyLinkedListImpl.java 2008-04-09
16:01:28 UTC (rev 19114)
@@ -63,7 +63,7 @@
//=== DoublyLinkedList implementation
======================================
/**
- * Reset the size of the list to zero.
+ * {@inheritDoc}
*/
public void clear() {
// Help to detect removal after clear().
@@ -86,20 +86,21 @@
}
/**
- * @return the number of items in the list
+ * {@inheritDoc}
*/
public final int size() {
return size;
}
/**
- * @return true if there are no items in the list
+ * {@inheritDoc}
*/
public final boolean isEmpty() {
return size == 0;
}
/**
+ * {@inheritDoc}
* @see #forwardElements()
*/
public final Enumeration elements() {
@@ -107,14 +108,14 @@
}
/**
- * @return the item at the head of the list, or null if empty
+ * {@inheritDoc}
*/
public final DoublyLinkedList.Item head() {
return size == 0 ? null : _headptr.next;
}
/**
- * @return the item at the tail of the list, or null if empty
+ * {@inheritDoc}
*/
public final DoublyLinkedList.Item tail() {
return size == 0 ? null : _tailptr.prev;
@@ -122,20 +123,29 @@
//=== methods that add/remove items at the head of the list
================
-
+ /**
+ * {@inheritDoc}
+ */
public final void unshift(DoublyLinkedList.Item i) {
insertNext(_headptr, i);
}
-
- // FIXME: unimplemented
+
+ /**
+ * {@inheritDoc}
+ * FIXME: unimplemented
+ */
public void unshift(DoublyLinkedList l) {
throw new RuntimeException("function currently unimplemented because i
am a lazy sod");
}
-
+ /**
+ * {@inheritDoc}
+ */
public final DoublyLinkedList.Item shift() {
return size == 0 ? null : remove(_headptr.next);
}
-
+ /**
+ * {@inheritDoc}
+ */
public DoublyLinkedList shift(int n) {
if (n > size) n = size;
@@ -165,20 +175,28 @@
//=== methods that add/remove items at the tail of the list
================
-
+ /**
+ * {@inheritDoc}
+ */
public final void push(DoublyLinkedList.Item i) {
insertPrev(_tailptr, i);
}
-
- // FIXME: unimplemented
+ /**
+ * {@inheritDoc}
+ * FIXME: unimplemented
+ */
public void push(DoublyLinkedList l) {
throw new RuntimeException("function currently unimplemented because i
am a lazy sod");
}
-
+ /**
+ * {@inheritDoc}
+ */
public final DoublyLinkedList.Item pop() {
return size == 0 ? null : remove(_tailptr.prev);
}
-
+ /**
+ * {@inheritDoc}
+ */
public DoublyLinkedList pop(int n) {
if (n > size) n = size;
@@ -208,22 +226,30 @@
//=== testing/looking at neighbor items
====================================
-
+ /**
+ * {@inheritDoc}
+ */
public final boolean hasNext(DoublyLinkedList.Item i) {
DoublyLinkedList.Item next = i.getNext();
return (next != null) && (next != _tailptr);
}
-
+ /**
+ * {@inheritDoc}
+ */
public final boolean hasPrev(DoublyLinkedList.Item i) {
DoublyLinkedList.Item prev = i.getPrev();
return (prev != null) && (prev != _headptr);
}
-
+ /**
+ * {@inheritDoc}
+ */
public final DoublyLinkedList.Item next(DoublyLinkedList.Item i) {
DoublyLinkedList.Item next = i.getNext();
return next == _tailptr ? null : next;
}
-
+ /**
+ * {@inheritDoc}
+ */
public final DoublyLinkedList.Item prev(DoublyLinkedList.Item i) {
DoublyLinkedList.Item prev = i.getPrev();
return prev == _headptr ? null : prev;
@@ -233,8 +259,7 @@
//=== insertion and removal of items
=======================================
/**
- * Remove the given item from the list.
- * @return this item, or null if the item was not in the list
+ * {@inheritDoc}
*/
public DoublyLinkedList.Item remove(DoublyLinkedList.Item i) {
if (i.getParent() == null) return null; // not in list
@@ -263,7 +288,7 @@
}
/**
- * Inserts item J before item I (going from head to tail).
+ * {@inheritDoc}
*/
public void insertPrev(DoublyLinkedList.Item i, DoublyLinkedList.Item j) {
if (i.getParent() == null)
@@ -285,16 +310,16 @@
++size;
}
- // FIXME: unimplemented
/**
- * Inserts the entire DoublyLinkedList L before item I.
+ * {@inheritDoc}
+ * FIXME: unimplemented
*/
public void insertPrev(DoublyLinkedList.Item i, DoublyLinkedList l) {
throw new RuntimeException("function currently unimplemented because i
am a lazy sod");
}
/**
- * Inserts item J after item I (going from head to tail).
+ * {@inheritDoc}
*/
public void insertNext(DoublyLinkedList.Item i, DoublyLinkedList.Item j) {
if (i.getParent() != this)
@@ -314,9 +339,9 @@
++size;
}
- // FIXME: unimplemented
/**
- * Inserts the entire DoublyLinkedList L after item I.
+ * {@inheritDoc}
+ * FIXME: unimplemented
*/
public void insertNext(DoublyLinkedList.Item i, DoublyLinkedList l) {
throw new RuntimeException("function currently unimplemented because i
am a lazy sod");
@@ -436,7 +461,8 @@
//=== list element ====================================================
public static class Item implements DoublyLinkedList.Item {
- private DoublyLinkedList.Item next, prev;
+ private DoublyLinkedList.Item prev;
+ private DoublyLinkedList.Item next;
private DoublyLinkedList list;
public Object clone() {
if(getClass() != Item.class)
Modified:
trunk/freenet/src/freenet/support/math/BootstrappingDecayingRunningAverage.java
===================================================================
---
trunk/freenet/src/freenet/support/math/BootstrappingDecayingRunningAverage.java
2008-04-09 16:01:05 UTC (rev 19113)
+++
trunk/freenet/src/freenet/support/math/BootstrappingDecayingRunningAverage.java
2008-04-09 16:01:28 UTC (rev 19114)
@@ -12,8 +12,8 @@
* @author amphibian
*
* For the first <tt>maxReports</tt> reports, this is equivalent to a simple
running average.
- * After that it is a decaying running average with a <tt>decayFactor</tt> of
<tt>1/maxReports</tt>. We
- * accomplish this by having <tt>decayFactor = 1/(Math.min(#reports + 1,
maxReports))</tt>. We can
+ * After that it is a decaying running average with a <tt>decayFactor</tt> of
<tt>1 / maxReports</tt>. We
+ * accomplish this by having <tt>decayFactor = 1/(Math.min(#reports,
maxReports))</tt>. We can
* therefore:
* <ul>
* <li>Specify <tt>maxReports</tt> more easily than an arbitrary decay
factor.</li>
@@ -83,9 +83,12 @@
}
/**
- * Not a public method. Changes the internally stored currentValue,
returning the old one.
- * Used from DecayingKeyspaceAverager to normalize the stored averages.
Calling this function
+ * <strong>Not a public method.</strong> Changes the internally stored
<code>currentValue</code> and return the old one.
+ *
+ * Used by {@link DecayingKeyspaceAverage} to normalize the stored
averages. Calling this function
* may (purposefully) destroy the utility of the average being kept.
+ *
+ * @see DecayingKeyspaceAverage
*/
protected synchronized double setCurrentValue(double d) {
double old=currentValue;
