Even further documentation updates for the 1.1.0 release

braille/src/org/daisy/braille/pef/PEFHandler.java

@@ -43,6 +43,9 @@ public class PEFHandler extends DefaultHandler {
 	 * @deprecated deprecated in public API, use Alignment
 	 */
 	public static enum AlignmentFallback {LEFT, CENTER_LEFT, CENTER_RIGHT, RIGHT, ABORT};
+	/**
+	 * Defines alignment values
+	 */
 	public static enum Alignment {
 		/**
 		 * Align left
@@ -99,7 +102,6 @@ public static enum Alignment {
 	/**
 	 * Provides a Builder for PEFHandler
 	 * @author Joel Håkansson
-	 *
 	 */
 	public static class Builder {
 		//required params
@@ -115,13 +117,16 @@ public static class Builder {
 
 		/**
 		 * Create a new PEFHandler builder
-		 * @param embosser 
+		 * @param embosser the embosser writer to use
 		 */
 		public Builder(EmbosserWriter embosser) {
 			this.embosser = embosser;
 		}
 
 		//init optional params here
+		/**
+		 * Sets the range of pages to output
+		 */
 		public Builder range(Range value) {
 			if (value!=null && !"".equals(value)) {
 				range = value;
@@ -157,6 +162,11 @@ public Builder mirrorAlignment(boolean value) {
 			mirrorAlign = value;
 			return this;
 		}
+		/**
+		 * Sets page alignment to use if the physical paper is bigger than the pages 
+		 * @param value the value to use
+		 * @return returns this object
+		 */
 		public Builder align(Alignment value) {
 			switch (value) {
 				case LEFT:
@@ -192,16 +202,30 @@ public Builder align(Alignment value) {
 			}
 			return this;
 		}
+		/**
+		 * Sets the page margin offset where positive numbers adjust towards
+		 * the right side of the paper, and negative numbers adjust towards the
+		 * left side.
+		 * @param value the offset
+		 * @return returns this object
+		 */
 		public Builder offset(int value) {
 			offset = value;
 			return this;
 		}
 //**** Added by Bert Frees *****************************************
+		/**
+		 * Sets the top offset.
+		 */
 		public Builder topOffset(int value) {
 			topOffset = value;
 			return this;
 		}
 //****************************************************************** 
+		/**
+		 * Builds a PEFHandler from this builder's current configuration.
+		 * @return returns a new PEFHandler 
+		 */
 		public PEFHandler build() throws IOException {
 			return new PEFHandler(this);
 		}

braille/src/org/daisy/braille/pef/PEFValidator.java

@@ -54,6 +54,9 @@ public class PEFValidator extends AbstractFactory implements org.daisy.validator
 	 * corresponding value should be a {@link Mode} value
 	 */
 	public final static String FEATURE_MODE = "validator mode";
+	/**
+	 * Defines the modes available to the validator.
+	 */
 	public enum Mode {
 		/**
 		 * Light mode validation only validates the document against the Relax NG schema

braille/src/org/daisy/braille/pef/TextHandler.java

@@ -89,42 +89,78 @@ public Builder(File input, File output) {
 		}
 
 		//init optional params here
+		/**
+		 * Sets the title for publications created using TextHandlers created with this builder.
+		 * @param value the title
+		 * @return returns this object
+		 */
 		public Builder title(String value) {
 			if (value==null) throw new IllegalArgumentException("Null value not accepted.");
 			title = value; return this; 
 		}
+		/**
+		 * Sets the author for publications created using TextHandlers created with this builder.
+		 * @param value the author
+		 * @return returns this object
+		 */
 		public Builder author(String value) {
 			if (value==null) throw new IllegalArgumentException("Null value not accepted.");
 			author = value; return this;
 		}
+		/**
+		 * Sets the language for publications created using TextHandlers created with this builder.
+		 * @param value the language
+		 * @return returns this object
+		 */
 		public Builder language(String value) {
 			if (value==null) throw new IllegalArgumentException("Null value not accepted.");
 			language = value; return this;
 		}
+		/**
+		 * Sets the identifier for publications created using TextHandlers created with this builder.
+		 * @param value the identifier
+		 * @return returns this object
+		 */
 		public Builder identifier(String value) {
 			if (value==null) throw new IllegalArgumentException("Null value not accepted.");
 			identifier = value; return this;
 		}
+		/**
+		 * Sets the converter identifier to be used when creating a TextHandler. See TableCatalog
+		 * for available values. If none is suppled, the builder will attempt to select one
+		 * based on file input characteristics.
+		 * @param value the identifier for the converter
+		 * @return returns this object
+		 */
 		public Builder converterId(String value) {
 			converterId = value;
 			return this;
 		}
+		/**
+		 * Sets the duplex property for publications created using TextHandlers created with this builder.
+		 * @param value the duplex value
+		 * @return returns this object
+		 */
 		public Builder duplex(boolean value) {
 			duplex = value; return this;
 		}
+		/**
+		 * Sets the date for publications created using TextHandlers created with this builder.
+		 * @param value the date to use
+		 * @return returns this object
+		 */
 		public Builder date(Date value) {
 			if (value==null) throw new IllegalArgumentException("Null value not accepted.");
 			date = value; return this;
 		}
-
-
-
 		/**
 		 * Builds a TextParser using the settings of this Builder
 		 * @return returns a new TextParser
 		 * @throws UnsupportedEncodingException
 		 */
-		public TextHandler build() throws IOException, InputDetectionException {	return new TextHandler(this); }
+		public TextHandler build() throws IOException, InputDetectionException {
+			return new TextHandler(this);
+		}
 	}
 
 	private TextHandler(Builder builder) throws IOException, InputDetectionException {

braille/src/org/daisy/braille/table/AdvancedBrailleConverter.java

@@ -40,24 +40,30 @@ public class AdvancedBrailleConverter implements BrailleConverter {
 	private final boolean supports8dot;
 
 	/**
-	 * Creates a new 6-dot table
-	 * @param table
-	 * @param charset
-	 * @param fallback
-	 * @param replacement
-	 * @param ignoreCase
-	 * @param mode
+	 * Creates a new 6-dot table. Each string in the table array represents a braille character.
+	 * The string at index <tt>i</tt> in the array is interpreted as the 
+	 * translation for the braille character with Unicode value 0x2800+i.
+	 * @param table the table data, 64 entries
+	 * @param charset the preferred charset as defined in the BrailleConverter interface
+	 * @param fallback the fallback method to use when encountering a character in the range 0x2840-0x28FF
+	 * @param replacement the replacement character, must be in the range 0x2800-0x283F
+	 * @param ignoreCase set to true to ignore character case
+	 * @param mode the match mode to use
+	 * @throws throws IllegalArgumentException if the table length isn't equal to 64
 	 */
 	public AdvancedBrailleConverter(String[] table, Charset charset, EightDotFallbackMethod fallback, char replacement, boolean ignoreCase, MatchMode mode) {
 		this(table, charset, fallback, replacement, ignoreCase, false, mode);
 	}
 
 	/**
-	 * Creates a new 8-dot table
-	 * @param table
-	 * @param charset
-	 * @param ignoreCase
-	 * @param mode
+	 * Creates a new 8-dot table. Each string in the table array represents a braille character.
+	 * The string at index <tt>i</tt> in the array is interpreted as the 
+	 * translation for the braille character with Unicode value 0x2800+i.
+	 * @param table the table data, 256 entries
+	 * @param charset the preferred charset as defined in the BrailleConverter interface
+	 * @param ignoreCase set to true to ignore character case
+	 * @param mode the match mode to use
+	 * @throws throws IllegalArgumentException if the table length isn't equal to 256
 	 */
 	public AdvancedBrailleConverter(String[] table, Charset charset, boolean ignoreCase, MatchMode mode) {
 		this(table, charset, EightDotFallbackMethod.MASK, null, ignoreCase, true, mode);

braille/src/org/daisy/braille/table/BrailleConverter.java

@@ -53,7 +53,7 @@ public interface BrailleConverter {
 	public Charset getPreferredCharset();
 
 	/**
-	 * 
+	 * Returns true if 8-dot braille is supported, false otherwise
 	 * @return returns true if 8-dot braille is supported, false otherwise
 	 */
 	public boolean supportsEightDot();

braille/src/org/daisy/braille/table/EmbosserBrailleConverter.java

@@ -27,8 +27,23 @@
  * @author Joel Håkansson
  */
 public class EmbosserBrailleConverter implements BrailleConverter {
+	/**
+	 * Defines the fallback action when a character in the range 0x2840-0x28FF is
+	 * encountered.
+	 */
 	public enum EightDotFallbackMethod {
-		MASK, REPLACE, REMOVE
+		/**
+		 * Mask the character. Treat it as if dots 7 and 8 were off
+		 */
+		MASK,
+		/**
+		 * Replace the character with a fixed replacement character 
+		 */
+		REPLACE,
+		/**
+		 * Remove the character from output
+		 */
+		REMOVE
 	}; // , FAIL
 	private HashMap<Character, Character> b2t;
 	private HashMap<Character, Character> t2b;
@@ -41,10 +56,10 @@ public enum EightDotFallbackMethod {
 	/**
 	 * Creates a new EmbosserBrailleConverter
 	 * @param table the characters in the table, in Unicode order. Must contain 64 or 256 characters.
-	 * @param charset 
-	 * @param fallback
-	 * @param replacement
-	 * @param ignoreCase
+	 * @param charset the preferred charset as defined in the BrailleConverter interface
+	 * @param fallback the fallback method to use when encountering a character in the range 0x2840-0x28FF
+	 * @param replacement the replacement character, must be in the range 0x2800-0x283F
+	 * @param ignoreCase set to true to ignore character case
 	 * @throws throws IllegalArgumentException if the table length isn't equal to 64 or 256.
 	 */
 	public EmbosserBrailleConverter(String table, Charset charset, EightDotFallbackMethod fallback, char replacement, boolean ignoreCase) {

braille/src/org/daisy/braille/table/EmbosserTable.java

@@ -20,6 +20,9 @@
 import java.util.HashMap;
 
 /**
+ * Provides an embosser table implementation. This implementation
+ * assumes that each character matches a single braille pattern,
+ * and vice versa. 
  * @author Joel Håkansson
  *
  * @param <T>
@@ -29,6 +32,13 @@ public class EmbosserTable<T> extends AbstractTable {
 	private final T type;
 	private final ConfigurableTableProvider<T> provider;
 
+	/**
+	 * Creates a new EmbosserTable with the supplied settings
+	 * @param name the name for the table
+	 * @param desc the description for the table
+	 * @param type the type of table
+	 * @param provider the provider
+	 */
 	public EmbosserTable(String name, String desc, T type, ConfigurableTableProvider<T> provider) {
 		super(name, desc, type.getClass().getCanonicalName() + "." + type.toString());
 		this.type = type;

braille/src/org/daisy/braille/table/TableProperties.java

@@ -17,7 +17,18 @@
  */
 package org.daisy.braille.table;
 
+/**
+ * Provides common table features. 
+ * @author Joel Håkansson
+ */
 public class TableProperties {
+	/**
+	 * Defines that table has a one-to-one mapping between character and braille pattern
+	 */
 	public final static String IS_ONE_TO_ONE = "is one-to-one";
+	/**
+	 * Defines that the table is meant for screen use, that is to say, 
+	 * does not contain binary type characters.
+	 */
 	public final static String IS_DISPLAY_FORMAT = "is display format";
 }

braille/src/org/daisy/braille/tools/StringTranslator.java

@@ -26,6 +26,9 @@
  *
  */
 public class StringTranslator {
+	/**
+	 * Defines the mode to use when matching patterns in the StringTranslator.
+	 */
 	public enum MatchMode {
 		/**
 		 * Defines the greedy approach to matching, where as much of the input as possible is used

braille/src/org/daisy/braille/ui/AbstractUI.java

@@ -75,15 +75,28 @@ public static class Definition {
 		private final String name;
 		private final String desc;
 
+		/**
+		 * Creates a new Definition.
+		 * @param name the name of the definition
+		 * @param desc the description of the definition
+		 */
 		public Definition(String name, String desc) {
 			this.name = name;
 			this.desc = desc;
 		}
 
+		/**
+		 * Gets the name of the definition
+		 * @return returns the name
+		 */
 		public String getName() {
 			return name;
 		}
 
+		/**
+		 * Gets the description of the definition
+		 * @return returns the description
+		 */
 		public String getDescription() {
 			return desc;
 		}