javadoc enhancements

IPAddress/src/inet.ipaddr/inet/ipaddr/format/util/AbstractTree.java

@@ -124,6 +124,9 @@ static <E extends Address> E checkBlockOrAddress(E addr, boolean thro) {
 		return null;
 	}
 
+	/**
+	 * Removes all added nodes from the tree, after which {@link #isEmpty()} will return true
+	 */
 	public void clear() {
 		getRoot().clear();
 	}

IPAddress/src/inet.ipaddr/inet/ipaddr/format/util/AddressTrie.java

@@ -1665,6 +1665,7 @@ public int size() {
 		}
 		return totalCount;
 	}
+
 	@Override
 	public boolean add(E addr) {
 		addr = checkBlockOrAddress(addr, true);
@@ -2430,6 +2431,11 @@ private TrieNode<E> getIteratingLowerBoundary() {
 		return subRoot.getParent();
 	}
 
+	/**
+	 * Returns a comparator for the trie order
+	 * 
+	 * @return
+	 */
 	public Comparator<E> getComparator() {
 		return comparator();
 	}
@@ -2623,6 +2629,9 @@ public AddressTrie<E> clone() {
 		return result;
 	}
 
+	/**
+	 * Returns whether the given argument is a trie with a set of nodes that equal the set of nodes in this trie
+	 */
 	@Override
 	public boolean equals(Object o) {
 		return o instanceof AddressTrie && super.equals(o);
@@ -2659,6 +2668,13 @@ void printTree(StringBuilder builder, Indents indents, boolean withNonAddedKeys)
 				this.<Indents>containingFirstAllNodeIterator(true));
 	}
 
+	/**
+	 * Produces a visual representation of the given tries joined by a single root node, with one node per line.
+	 * 
+	 * @param withNonAddedKeys
+	 * @param tries
+	 * @return
+	 */
 	public static String toString(boolean withNonAddedKeys, AddressTrie<?> ...tries) {
 		StringBuilder builder = new StringBuilder('\n' + BinaryTreeNode.NON_ADDED_NODE_CIRCLE);
 		String topLabel =  ' ' + Address.SEGMENT_WILDCARD_STR;

IPAddress/src/inet.ipaddr/inet/ipaddr/format/util/AddressTrieMap.java

@@ -418,6 +418,13 @@ public V get(Object key) {
 		return trie.get((K) key);
 	}
 
+	/**
+	 * Maps the given single address or prefix block subnet to the given value in the map.
+	 * <p>
+	 * If the given address is not a single address nor prefix block, then this method throws IllegalArgumentException. 
+	 * <p>
+	 * See {@link AssociativeAddressTrie}
+	 */
 	@Override
 	public V put(K key, V value) {
 		return trie.put(key, value);

IPAddress/src/inet.ipaddr/inet/ipaddr/format/util/AddressTrieSet.java

@@ -259,6 +259,13 @@ public boolean contains(Object o) {
 		return trie.contains((E) o);
 	}
 
+	/**
+	 * Adds the given single address or prefix block subnet to this set.
+	 * <p>
+	 * If the given address is not a single address nor prefix block, then this method throws IllegalArgumentException. 
+	 * <p>
+	 * See {@link AddressTrie}
+	 */
 	@Override
 	public boolean add(E e) {
 		return trie.add(e);

IPAddress/src/inet.ipaddr/inet/ipaddr/format/util/BinaryTreeNode.java

@@ -44,10 +44,10 @@
  * When removing nodes, non-added nodes are removed automatically whenever they are no longer needed,
  * which is when an added node has less than two added sub-nodes.
  * <p>
- * You cannot create nodes directly, instead they are created indirectly by tree operations or by cloning existing nodes.
+ * BinaryTreeNode objects have a read-only API, in the sense that they cannot be constructed directly.
+ * Instead they are created indirectly by tree operations or by cloning existing nodes.
  * <p>
- * BinaryTreeNode objects have a read-only API.  This is because they are managed by trees.  
- * They can be used to traverse the structure of a tree. 
+ * The API does allow you to remove them from trees, or to clone them.  They can also be used to traverse a tree. 
  * <p>
  * Nodes have various properties: the key, parent node, lower sub-node, upper sub-node, "added" property, and size.  
  * The "added" property can change if the node changes status following tree operations.
@@ -514,6 +514,7 @@ protected void setKey(E item) {
 	}
 
 	/**
+	 * Gets the key used for placing the node in the tree.
 	 * 
 	 * @return the key used for placing the node in the tree.
 	 */
@@ -530,6 +531,11 @@ public boolean isRoot() {
 		return parent == null;
 	}
 
+	/**
+	 * Gets the node from which this node is a direct child node, or null if this is the root.
+	 * 
+	 * @return
+	 */
 	public BinaryTreeNode<E> getParent() {
 		return parent;
 	}
@@ -539,7 +545,7 @@ void setParent(BinaryTreeNode<E> parent) {
 	}
 
 	/**
-	 * Gets the node whose key is largest in value
+	 * Gets the direct child node whose key is largest in value
 	 * 
 	 * @return
 	 */
@@ -548,7 +554,7 @@ public BinaryTreeNode<E> getUpperSubNode() {
 	}
 
 	/**
-	 * Gets the node whose key is smallest in value
+	 * Gets the direct child node whose key is smallest in value
 	 * 
 	 * @return
 	 */
@@ -749,7 +755,7 @@ protected void replaceThisRoot(BinaryTreeNode<E> replacement) {
 	}
 
 	/**
-	 * Removes this node and all sub-nodes, after which isEmpty() will return true.
+	 * Removes this node and all sub-nodes from the tree, after which isEmpty() will return true.
 	 */
 	public void clear() {
 		replaceThis(null);
@@ -2286,6 +2292,13 @@ static class Indents {
 		}
 	}
 
+	/**
+	 * Returns a visual representation of the sub-tree with this node as root, with one node per line.
+	 * 
+	 * @param withNonAddedKeys whether to show nodes that are not added nodes
+	 * @param withSizes whether to include the counts of added nodes in each sub-tree
+	 * @return
+	 */
 	public String toTreeString(boolean withNonAddedKeys, boolean withSizes) {
 		StringBuilder builder = new StringBuilder("\n");
 		printTree(builder, new Indents(), withNonAddedKeys, withSizes, this.<Indents>containingFirstAllNodeIterator(true));
@@ -2338,6 +2351,10 @@ void printTree(StringBuilder builder,
 		}
 	}
 
+	/**
+	 * Returns a visual representation of this node including the key, with an open circle indicating this node is not an added node,
+	 * a closed circle indicating this node is an added node.
+	 */
 	@Override
 	public String toString() {
 		return (isAdded() ? ADDED_NODE_CIRCLE + ' ' : NON_ADDED_NODE_CIRCLE + ' ') + getNodeIdentifier();

IPAddress/src/inet.ipaddr/inet/ipaddr/ipv4/IPv4AddressSection.java

@@ -60,7 +60,6 @@
 import inet.ipaddr.ipv4.IPv4AddressNetwork.IPv4AddressCreator;
 import inet.ipaddr.ipv4.IPv4AddressSection.IPv4StringCollection.IPv4AddressSectionStringCollection;
 import inet.ipaddr.ipv4.IPv4AddressSection.IPv4StringCollection.IPv4StringBuilder;
-import inet.ipaddr.ipv6.IPv6AddressSection;
 import inet.ipaddr.ipv6.IPv6Address.IPv6AddressConverter;
 import inet.ipaddr.ipv6.IPv6AddressSection.IPv6StringBuilderOptions;
 
@@ -1908,7 +1907,7 @@ protected static IPAddressSegmentSeries coverWithPrefixBlock(
 	/**
 	 * Produces an array of prefix blocks that spans the same set of values.
 	 * <p>
-	 * Unlike {@link #spanWithPrefixBlocks(IPv6AddressSection)} this method only includes blocks that are a part of this section.
+	 * Unlike {@link #spanWithPrefixBlocks(IPv4AddressSection)} this method only includes blocks that are a part of this section.
 	 */
 	@Override
 	public IPv4AddressSection[] spanWithPrefixBlocks() {
@@ -1957,7 +1956,7 @@ public IPv4AddressSection[] spanWithRangedSegments(IPv4AddressSection other) {
 	 * <p>
 	 * This array can be shorter than that produced by {@link #spanWithPrefixBlocks()} and is never longer.
 	 * <p>
-	 * Unlike {@link #spanWithSequentialBlocks(IPv6AddressSection)} this method only includes values that are a part of this section.
+	 * Unlike {@link #spanWithSequentialBlocks(IPv4AddressSection)} this method only includes values that are a part of this section.
 	 */
 	@Override
 	public IPv4AddressSection[] spanWithSequentialBlocks() throws AddressConversionException {

IPAddress/src/inet.ipaddr/inet/ipaddr/ipv6/IPv6Address.java

@@ -85,6 +85,7 @@
  * <li>They are used with link-local addresses fe80::/10 to distinguish two interfaces to the link-local network, this is known as the zone id.
  * </li><li>They are used with site-local addresses to distinguish sites, using the site id, also known as the scope id.
  * </li></ul>
+ * <p>
  * A zone that consists of a scope id is called a scoped zone.
  * @custom.core
  * @author sfoley
@@ -157,6 +158,7 @@ public class IPv6Address extends IPAddress implements Iterable<IPv6Address> {
 	 * or to look up the associated interface if the instance references by scope id.
 	 * 
 	 * 
+	 * @custom.core
 	 * @author scfoley
 	 *
 	 */
@@ -170,15 +172,18 @@ public static class IPv6Zone implements Serializable {
 		private Boolean referencesInterface;
 
 		/**
-		 * Constructs a zone that will use a scope identifier with the address if the given string
-		 * is a non-negative integer, indicated by a sequence of decimal digits.
-		 * Otherwise, the string will be presumed to be the name of an interface.
+		 * Constructs a zone that will use the given zone string, 
+		 * either a non-negative integer indicating a scope identifier, 
+		 * or the name of a network interface.
+		 * <p>
+		 * A scope identifier is indicated by a sequence of decimal digits.
+		 * <p>
 		 * To create an InetAddress by pairing this zone with an IPv6Address instance,
-		 * the interface name must reference an existing interface, otherwise the InetAddress cannot be created.
+		 * an interface name must reference an existing interface, otherwise the InetAddress cannot be created.
 		 * <p>
 		 * See {@link java.net.NetworkInterface}  to get a list of existing interfaces or to look up interfaces by name.
 		 * 
-		 * @param scopeId
+		 * @param zoneStr
 		 */
 		public IPv6Zone(String zoneStr) {
 			if(zoneStr == null) {
@@ -204,7 +209,7 @@ public IPv6Zone(int scopeId) {
 		/**
 		 * Constructs a zone that will use an interface name with the address.
 		 * 
-		 * @param scopeId
+		 * @param networkInterface
 		 */
 		public IPv6Zone(NetworkInterface networkInterface) {
 			if(networkInterface == null) {
@@ -446,7 +451,7 @@ public IPv6Address(IPv6AddressSegment[] segments, Integer networkPrefixLength) t
 	/**
 	 * Constructs an IPv6 address or a set of addresses.
 	 * 
-	 * @deprecated {@link #IPv6Address(IPv6AddressSegment[], IPv6Zone)}
+	 * @deprecated use {@link #IPv6Address(IPv6AddressSegment[], IPv6Zone)}
 	 * @param segments the address segments
 	 * @param zone the zone or scope id
 	 * 
@@ -748,7 +753,7 @@ public IPv6Address(SegmentValueProvider valueProvider) {
 	/**
 	 * Constructs an IPv6 address.
 	 *
-	 * @deprecated use {@link #IPv6Address(SegmentValueProvider, SegmentValueProvider, IPv6Zone)}
+	 * @deprecated use {@link #IPv6Address(Address.SegmentValueProvider, Address.SegmentValueProvider, IPv6Zone)}
 	 * @param lowerValueProvider supplies the 2 byte lower values for each segment
 	 * @param upperValueProvider supplies the 2 byte upper values for each segment
 	 * @throws AddressValueException if zone is invalid