From c99e28a7888789f55d0c073e04609bdeec4ba452 Mon Sep 17 00:00:00 2001
From: Peter Palfrader <peter@palfrader.org>
Date: Tue, 11 Nov 2003 18:28:23 +0000
Subject: Document existing PathSpec code

---
 src/org/noreply/fancydress/type3/PathSpec.java | 67 +++++++++++++++++---------
 1 file changed, 44 insertions(+), 23 deletions(-)

diff --git a/src/org/noreply/fancydress/type3/PathSpec.java b/src/org/noreply/fancydress/type3/PathSpec.java
index 9e975c6..bf5f1b5 100644
--- a/src/org/noreply/fancydress/type3/PathSpec.java
+++ b/src/org/noreply/fancydress/type3/PathSpec.java
@@ -15,6 +15,13 @@ public class PathSpec {
 	PathComponent[] pathComponents;
 	boolean singleLeg;
 
+	/**
+	 * Class to hold one path component.
+	 *
+	 * A path component is either a component as defined in the mixminion
+	 * path-spec, like a hop by nickname, one or more random hops, or
+	 * gaussian hops; or it is the crossover point of a two-leg path spec.
+	 */
 	private class PathComponent {
 		public final static double GAUSS_STD_DEV = 1.5;
 
@@ -26,6 +33,12 @@ public class PathSpec {
 		Server byNickname;
 		int numRandoms;
 
+		/**
+		 * Constructor.
+		 *
+		 * @param dir A mixminion directory
+		 * @param component the string representation of that component
+		 */
 		public PathComponent(Directory dir, String component) throws Mix3BadArgumentsIllegalPathSpecException {
 			String c = component.trim();
 			if (c.equals(""))
@@ -75,10 +88,20 @@ public class PathSpec {
 			}
 		}
 
+		/**
+		 * If this path component is the crossover point.
+		 *
+		 * @return true if this path component is the crossover point.
+		 */
 		public boolean isCrossover() {
 			return (type == TYPE_CROSSOVER);
 		}
 
+		/**
+		 * Get a number of hops statisfyi8ng this path component.
+		 *
+		 * @throws Error if this path spec is the crossover point.
+		 */
 		public Server[] getHops() {
 			Server[] result;
 			switch (type) {
@@ -94,6 +117,8 @@ public class PathSpec {
 					int num = (int) (d+0.5);
 					result = new Server[ num<0 ? 0 : num ];
 					break;
+				case TYPE_CROSSOVER :
+					throw new Error("getHops() may not be called on the crossover point ");
 				default :
 					throw new Error("Unkown type "+type);
 			}
@@ -101,6 +126,13 @@ public class PathSpec {
 		}
 	}
 
+	/**
+	 * Split a string on an optional crossover point, given by the
+	 * separator token (colon).
+	 *
+	 * @param tokens the list of tokens to which the one or two new tokens are added.
+	 * @param s the string to split.
+	 */
 	private void splitCrossover(ArrayList tokens, String s) throws Mix3BadArgumentsIllegalPathSpecException {
 		int indexOf = s.indexOf(':');
 		if (indexOf != -1) {
@@ -119,6 +151,13 @@ public class PathSpec {
 		}
 	}
 
+	/**
+	 * Parses a pathspec and returns an array of path components.
+	 *
+	 * @param dir A mixminion directory
+	 * @param path the path specification to parse
+	 * @return An array of PathComponent objects representing this pathSpec.
+	 */
 	private PathComponent[] parsePath(Directory dir, String path) throws Mix3BadArgumentsIllegalPathSpecException {
 		ArrayList nicks = new ArrayList();
 		String[] tokens = Util.tokenize(path, ',');
@@ -138,8 +177,6 @@ public class PathSpec {
 	 *
 	 * A path spec could look like "<code>Foo,Bar,?:Baz,*2,~1</code>".
 	 *
-	 * FIXME: right now we don't do any random foo.
-	 *
 	 * @param path given path
 	 */
 	public PathSpec(Directory dir, String pathSpec, boolean singleLeg) throws Mix3BadArgumentsIllegalPathSpecException {
@@ -162,6 +199,9 @@ public class PathSpec {
 		this.pathComponents = parsePath(dir, pathSpec);
 	}
 
+	/**
+	 * A class holding a list of Servers and a Crossover point location.
+	 */
 	private class ServerWithCrossover {
 		public Server[] servers;
 		public int crossoverPoint;
@@ -226,6 +266,8 @@ public class PathSpec {
 
 	/**
 	 * Concat path components, getting random amount of hops where requested.
+	 *
+	 * @return a list of servers and a crossover point as an ServerWithCrossover object.
 	 */
 	private ServerWithCrossover concatComponents() throws Mix3PathProblemException {
 		Server[][] components = new Server[pathComponents.length][];
@@ -256,27 +298,6 @@ public class PathSpec {
 		return result;
 	}
 
-	/**
-	 * get one instance of this path spec.
-	 * 
-	 * Also we filter acceptable exit nodes according to the payload's
-	 * constraints.
-	 *
-	 * @return one path constructed from the PathSpec
-	 */
-	/*
-	private Object getPathInstance() throws Mix3PathProblemException {
-
-		ServerWithCrossover path = concatComponents();
-		fillInRandoms(path.components);
-
-		if (singleLeg)
-			throw new Error("not implemented yet"); // FIXME
-		else
-			return path.getPath();
-	}
-	*/
-
 	/**
 	 * Return paths constructed from this PathSpec.
 	 *
-- 
cgit v1.2.3