Javadoc improvements

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/branches/Temp_TrueTypeInPostScript@1344309 13f79535-47bb-0310-9956-ffa450edef68

13 files changed, 99 insertions, 106 deletions

diff --git a/src/java/org/apache/fop/fonts/CustomFont.java b/src/java/org/apache/fop/fonts/CustomFont.java
index b506393a6..89f515205 100644
--- a/src/java/org/apache/fop/fonts/CustomFont.java
+++ b/src/java/org/apache/fop/fonts/CustomFont.java
@@ -493,9 +493,9 @@ public abstract class CustomFont extends Typeface
     }
 
     /**
-     * Sets the identity character map for this font. It maps all available Unicode characters
+     * Sets the character map for this font. It maps all available Unicode characters
      * to their glyph indices inside the font.
-     * @param cmap the identity character map
+     * @param cmap the character map
      */
     public void setCMap(CMapSegment[] cmap) {
         this.cmap = new CMapSegment[cmap.length];
@@ -503,9 +503,9 @@ public abstract class CustomFont extends Typeface
     }
 
     /**
-     * Returns the identity character map for this font. It maps all available Unicode characters
+     * Returns the character map for this font. It maps all available Unicode characters
      * to their glyph indices inside the font.
-     * @return the identity character map
+     * @return the character map
      */
     public CMapSegment[] getCMap() {
         CMapSegment[] copy = new CMapSegment[cmap.length];
diff --git a/src/java/org/apache/fop/fonts/EmbedFontInfo.java b/src/java/org/apache/fop/fonts/EmbedFontInfo.java
index 4287e6938..64bd200be 100644
--- a/src/java/org/apache/fop/fonts/EmbedFontInfo.java
+++ b/src/java/org/apache/fop/fonts/EmbedFontInfo.java
@@ -188,7 +188,7 @@ public class EmbedFontInfo implements Serializable {
     }
 
     /**
-     * Sets the embedding mode for this font, currently not supported for type1 fonts.
+     * Sets the embedding mode for this font, currently not supported for Type 1 fonts.
      * @param embeddingMode the new embedding mode.
      */
     public void setEmbeddingMode(EmbeddingMode embeddingMode) {
diff --git a/src/java/org/apache/fop/fonts/EmbeddingMode.java b/src/java/org/apache/fop/fonts/EmbeddingMode.java
index 89f56cfd7..d75c7a3d4 100644
--- a/src/java/org/apache/fop/fonts/EmbeddingMode.java
+++ b/src/java/org/apache/fop/fonts/EmbeddingMode.java
@@ -21,10 +21,10 @@ package org.apache.fop.fonts;
 
 /**
  * This enumerates the embedding mode of fonts; full; subset; auto (auto defaults to full for
- * type1 fonts and subset for truetype fonts.
+ * Type 1 fonts and subset for TrueType fonts.
  */
 public enum EmbeddingMode {
-    /** Default option: assumes FULL for type1 fonts and SUBSET for truetype fonts. */
+    /** Default option: assumes FULL for Type 1 fonts and SUBSET for TrueType fonts. */
     AUTO,
     /** Full font embedding: This means the whole of the font is written to file. */
     FULL,
@@ -34,16 +34,16 @@ public enum EmbeddingMode {
 
     /**
      * Returns the name of this embedding mode.
-     * @return String - lower case.
+     * @return the name of this embedding mode in lower case.
      */
     public String getName() {
         return this.toString().toLowerCase();
     }
 
     /**
-     * Returns {@link EmbeddingMode} by name.
-     * @param value String - the name of the embedding mode (not case sensitive).
-     * @return embedding mode constant.
+     * Returns the embedding mode corresponding to the given name.
+     * @param value the name of an embedding mode (not case sensitive)
+     * @return the corresponding embedding mode
      */
     public static EmbeddingMode getValue(String value) {
         for (EmbeddingMode mode : EmbeddingMode.values()) {
diff --git a/src/java/org/apache/fop/fonts/FontType.java b/src/java/org/apache/fop/fonts/FontType.java
index 06bbf1bc1..edd8d0c37 100644
--- a/src/java/org/apache/fop/fonts/FontType.java
+++ b/src/java/org/apache/fop/fonts/FontType.java
@@ -130,7 +130,7 @@ public class FontType {
         return value;
     }
 
-    /** {@inheritDoc} */
+    @Override
     public String toString() {
         return name;
     }
diff --git a/src/java/org/apache/fop/fonts/MutableFont.java b/src/java/org/apache/fop/fonts/MutableFont.java
index adbf3b250..3ebc3c465 100644
--- a/src/java/org/apache/fop/fonts/MutableFont.java
+++ b/src/java/org/apache/fop/fonts/MutableFont.java
@@ -61,8 +61,8 @@ public interface MutableFont {
     void setEmbedResourceName(String name);
 
     /**
-     * Set the embedding mode for this font.
-     * @param embeddingMode the embedding mode.
+     * Sets the embedding mode.
+     * @param embeddingMode the embedding mode
      */
     void setEmbeddingMode(EmbeddingMode embeddingMode);
 
diff --git a/src/java/org/apache/fop/fonts/truetype/TTFFile.java b/src/java/org/apache/fop/fonts/truetype/TTFFile.java
index 77cdddcdd..1ec4120a6 100644
--- a/src/java/org/apache/fop/fonts/truetype/TTFFile.java
+++ b/src/java/org/apache/fop/fonts/truetype/TTFFile.java
@@ -142,8 +142,9 @@ public class TTFFile {
         "ccaron",           "dcroat"
     };
 
-    /** The FontFileReader used to read this truetype font */
+    /** The FontFileReader used to read this TrueType font. */
     protected FontFileReader fontFile;
+
     /** Set to true to get even more debug output than with level DEBUG */
     public static final boolean TRACE_ENABLED = false;
 
@@ -246,7 +247,7 @@ public class TTFFile {
     }
 
     /**
-     * Key-value helper class (immutable)
+     * Key-value helper class.
      */
     final class UnicodeMapping implements Comparable {
 
@@ -1699,7 +1700,7 @@ public class TTFFile {
 
     /**
      * Streams a font.
-     * @param ttfOut The interface for streaming True Type tables.
+     * @param ttfOut The interface for streaming TrueType tables.
      * @exception IOException file write error
      */
     public void stream(TTFOutputStream ttfOut) throws IOException {
@@ -1737,7 +1738,7 @@ public class TTFFile {
     }
 
     /**
-     * This returns the order in which the tables in a truetype font should be written to file.
+     * Returns the order in which the tables in a TrueType font should be written to file.
      * @param directoryTabs the map that is to be sorted.
      * @return TTFTablesNames[] an array of table names sorted in the order they should appear in
      * the TTF file.
diff --git a/src/java/org/apache/fop/fonts/truetype/TTFGlyphOutputStream.java b/src/java/org/apache/fop/fonts/truetype/TTFGlyphOutputStream.java
index ee3101f9b..313d5836d 100644
--- a/src/java/org/apache/fop/fonts/truetype/TTFGlyphOutputStream.java
+++ b/src/java/org/apache/fop/fonts/truetype/TTFGlyphOutputStream.java
@@ -22,27 +22,27 @@ package org.apache.fop.fonts.truetype;
 import java.io.IOException;
 
 /**
- * This is an interface for streaming individual glyphs from the glyf table in a True Type font.
+ * An interface for writing individual glyphs from the glyf table of a TrueType font to an output stream.
  */
 public interface TTFGlyphOutputStream {
+
     /**
      * Begins the streaming of glyphs.
-     * @throws IOException file write exception
      */
     void startGlyphStream() throws IOException;
 
     /**
-     * Streams an individual glyph at offset from a byte array.
-     * @param byteArray byte[] the font byte array.
-     * @param offset int the starting position to stream from.
-     * @param length int the number of bytes to stream.
-     * @throws IOException file write exception.
+     * Streams an individual glyph from the given byte array.
+     *
+     * @param glyphData the source of the glyph data to stream from
+     * @param offset the position in the glyph data where the glyph starts
+     * @param size the size of the glyph data in bytes
      */
-    void streamGlyph(byte[] byteArray, int offset, int length) throws IOException;
+    void streamGlyph(byte[] glyphData, int offset, int size) throws IOException;
 
     /**
      * Ends the streaming of glyphs.
-     * @throws IOException file write exception.
      */
     void endGlyphStream() throws IOException;
+
 }
diff --git a/src/java/org/apache/fop/fonts/truetype/TTFOutputStream.java b/src/java/org/apache/fop/fonts/truetype/TTFOutputStream.java
index 8fb8a5cc7..09b5b6f50 100644
--- a/src/java/org/apache/fop/fonts/truetype/TTFOutputStream.java
+++ b/src/java/org/apache/fop/fonts/truetype/TTFOutputStream.java
@@ -22,30 +22,28 @@ package org.apache.fop.fonts.truetype;
 import java.io.IOException;
 
 /**
- * This is an interface for streaming True Type font.
+ * An interface for writing a TrueType font to an output stream.
  */
 public interface TTFOutputStream {
+
     /**
-     * Starts writing the font to file.
-     * @throws IOException file write exception.
+     * Starts writing the font.
      */
     void startFontStream() throws IOException;
 
     /**
-     * Returns an object for streaming True Type tables.
-     * @return {@link TTFTableOutputStream}
+     * Returns an object for streaming TrueType tables.
      */
     TTFTableOutputStream getTableOutputStream();
 
     /**
-     * Returns an object for streaming True Type glyphs in the glyf table.
-     * @return {@link TTFGlyphOutputStream}
+     * Returns an object for streaming TrueType glyphs in the glyf table.
      */
     TTFGlyphOutputStream getGlyphOutputStream();
 
     /**
-     * Ends writing the font to file.
-     * @throws IOException file write exception.
+     * Ends writing the font.
      */
     void endFontStream() throws IOException;
+
 }
diff --git a/src/java/org/apache/fop/fonts/truetype/TTFSubSetFile.java b/src/java/org/apache/fop/fonts/truetype/TTFSubSetFile.java
index 094716a66..5e8fbb379 100644
--- a/src/java/org/apache/fop/fonts/truetype/TTFSubSetFile.java
+++ b/src/java/org/apache/fop/fonts/truetype/TTFSubSetFile.java
@@ -81,7 +81,7 @@ public class TTFSubSetFile extends TTFFile {
                         = new HashMap<TTFTableName, TTFDirTabEntry>();
 
     private int determineTableCount() {
-        int numTables = 4; //4 req'd tables: head,hhea,hmtx,maxp,
+        int numTables = 4; //4 req'd tables: head,hhea,hmtx,maxp
         if (isCFF()) {
             throw new UnsupportedOperationException(
                     "OpenType fonts with CFF glyphs are not supported");
@@ -126,7 +126,7 @@ public class TTFSubSetFile extends TTFFile {
 
         writeUShort((numTables * 16) - searchRange);
         realSize += 2;
-     // Create space for the table entries (these must be in ASCII alphabetical order[A-Z]then[a-z])
+        // Create space for the table entries (these must be in ASCII alphabetical order[A-Z] then[a-z])
         writeTableName(TTFTableName.OS2);
 
         if (hasCvt()) {
@@ -215,9 +215,6 @@ public class TTFSubSetFile extends TTFFile {
 
     /**
      * Copy the name table as is from the original.
-     * @param in FontFileReader
-     * @return boolean
-     * @throws IOException exception
      */
     private boolean createName(FontFileReader in) throws IOException {
         return copyTable(in, TTFTableName.NAME);
@@ -225,9 +222,6 @@ public class TTFSubSetFile extends TTFFile {
 
     /**
      * Copy the OS/2 table as is from the original.
-     * @param in
-     * @return
-     * @throws IOException
      */
     private boolean createOS2(FontFileReader in) throws IOException {
         return copyTable(in, TTFTableName.OS2);
@@ -389,7 +383,7 @@ public class TTFSubSetFile extends TTFFile {
                     endOffset1 = (currentPos - startPos + glyphLength);
                 }
 
-                // Store the glyph boundary positions relative to the start the font
+                // Store the glyph boundary positions relative to the start of the font
                 glyphOffsets[i] = currentPos;
                 currentPos += glyphLength;
                 realSize += glyphLength;
diff --git a/src/java/org/apache/fop/fonts/truetype/TTFTableName.java b/src/java/org/apache/fop/fonts/truetype/TTFTableName.java
index 0d071712b..cf66954b6 100644
--- a/src/java/org/apache/fop/fonts/truetype/TTFTableName.java
+++ b/src/java/org/apache/fop/fonts/truetype/TTFTableName.java
@@ -21,95 +21,96 @@ package org.apache.fop.fonts.truetype;
 
 
 /**
- * This class holds the True Type Format table names as in the Directory Table of a TTF font file.
- * This class must also support custom tables found in fonts (thus an enum wasn't used).
+ * Represents table names as found in a TrueType font's Table Directory.
+ * TrueType fonts may have custom tables so we cannot use an enum.
  */
 public final class TTFTableName {
-    /** The first table in a True Type font file containing metadata about other tables. */
+
+    /** The first table in a TrueType font file containing metadata about other tables. */
     public static final TTFTableName DIRECTORY_TABLE = new TTFTableName("dirTable");
 
-    /** Embedded bitmap data */
+    /** Embedded bitmap data. */
     public static final TTFTableName EBDT = new TTFTableName("EBDT");
 
-    /** Embedded bitmap location data */
+    /** Embedded bitmap location data. */
     public static final TTFTableName EBLC = new TTFTableName("EBLC");
 
-    /** Embedded bitmap scaling data */
+    /** Embedded bitmap scaling data. */
     public static final TTFTableName EBSC = new TTFTableName("EBSC");
 
-    /** A font forge specific table */
+    /** A FontForge specific table. */
     public static final TTFTableName FFTM = new TTFTableName("FFTM");
 
     /** Divides glyphs into various classes that make using the GPOS/GSUB tables easier. */
     public static final TTFTableName GDEF = new TTFTableName("GDEF");
 
-    /** Provides kerning information, mark-to-base, etc. for opentype fonts */
+    /** Provides kerning information, mark-to-base, etc. for opentype fonts. */
     public static final TTFTableName GPOS = new TTFTableName("GPOS");
 
-    /** Provides ligature information, swash, etc. for opentype fonts */
+    /** Provides ligature information, swash, etc. for opentype fonts. */
     public static final TTFTableName GSUB = new TTFTableName("GSUB");
 
-    /** Linear threshold table */
+    /** Linear threshold table. */
     public static final TTFTableName LTSH = new TTFTableName("LTSH");
 
-    /** OS/2 and Windows specific metrics */
+    /** OS/2 and Windows specific metrics. */
     public static final TTFTableName OS2 = new TTFTableName("OS/2");
 
-    /** PCL 5 data*/
+    /** PCL 5 data. */
     public static final TTFTableName PCLT = new TTFTableName("PCLT");
 
-    /** Vertical Device Metrics table */
+    /** Vertical Device Metrics table. */
     public static final TTFTableName VDMX = new TTFTableName("VDMX");
 
-    /** character to glyph mapping */
+    /** Character to glyph mapping. */
     public static final TTFTableName CMAP = new TTFTableName("cmap");
 
-    /** Control Value Table */
+    /** Control Value Table. */
     public static final TTFTableName CVT = new TTFTableName("cvt ");
 
-    /** font program */
+    /** Font program. */
     public static final TTFTableName FPGM = new TTFTableName("fpgm");
 
-    /** grid-fitting and scan conversion procedure (grayscale) */
+    /** Grid-fitting and scan conversion procedure (grayscale). */
     public static final TTFTableName GASP = new TTFTableName("gasp");
 
-    /** glyph data */
+    /** Glyph data. */
     public static final TTFTableName GLYF = new TTFTableName("glyf");
 
-    /** horizontal device metrics */
+    /** Horizontal device metrics. */
     public static final TTFTableName HDMX = new TTFTableName("hdmx");
 
-    /** font header */
+    /** Font header. */
     public static final TTFTableName HEAD = new TTFTableName("head");
 
-    /** horizontal header */
+    /** Horizontal header. */
     public static final TTFTableName HHEA = new TTFTableName("hhea");
 
-    /** horizontal metrics */
+    /** Horizontal metrics. */
     public static final TTFTableName HMTX = new TTFTableName("hmtx");
 
-    /** kerning */
+    /** Kerning. */
     public static final TTFTableName KERN = new TTFTableName("kern");
 
-    /** index to location */
+    /** Index to location. */
     public static final TTFTableName LOCA = new TTFTableName("loca");
 
-    /** maximum profile */
+    /** Maximum profile. */
     public static final TTFTableName MAXP = new TTFTableName("maxp");
 
-    /** naming table */
+    /** Naming table. */
     public static final TTFTableName NAME = new TTFTableName("name");
 
-    /** PostScript information */
+    /** PostScript information. */
     public static final TTFTableName POST = new TTFTableName("post");
 
-    /** CVT Program */
+    /** CVT Program. */
     public static final TTFTableName PREP = new TTFTableName("prep");
 
-    /** Vertical Metrics header */
+    /** Vertical Metrics header. */
     public static final TTFTableName VHEA = new TTFTableName("vhea");
 
-    /** Vertical Metrics */
+    /** Vertical Metrics. */
     public static final TTFTableName VMTX = new TTFTableName("vmtx");
 
     private final String name;
@@ -119,16 +120,15 @@ public final class TTFTableName {
     }
 
     /**
-     * Returns the name of the table as it should be in the Table Directory.
-     * @return String
+     * Returns the name of the table as it should be in the Directory Table.
      */
     public String getName() {
         return name;
     }
 
     /**
-     * Returns the appropriate TTFTableName object when given the string representation.
-     * @param tableName table name as in the Directory Table.
+     * Returns an instance of this class corresponding to the given string representation.
+     * @param tableName table name as in the Table Directory
      * @return TTFTableName
      */
     public static TTFTableName getValue(String tableName) {
diff --git a/src/java/org/apache/fop/fonts/truetype/TTFTableOutputStream.java b/src/java/org/apache/fop/fonts/truetype/TTFTableOutputStream.java
index 75f0ef63d..d0d2007f5 100644
--- a/src/java/org/apache/fop/fonts/truetype/TTFTableOutputStream.java
+++ b/src/java/org/apache/fop/fonts/truetype/TTFTableOutputStream.java
@@ -22,16 +22,16 @@ package org.apache.fop.fonts.truetype;
 import java.io.IOException;
 
 /**
- * An interface for streaming full True Type tables from a TTF file.
+ * An interface for writing a TrueType table to an output stream.
  */
 public interface TTFTableOutputStream {
 
     /**
-     * Streams a table defined in byteArray at offset of length bytes.
-     * @param byteArray The source of the table to stream from.
-     * @param offset The position in byteArray to begin streaming from.
-     * @param length The number of bytes to stream.
-     * @throws IOException write error.
+     * Streams a table from the given byte array.
+     *
+     * @param ttfData the source of the table to stream from
+     * @param offset the position in the byte array where the table starts
+     * @param size the size of the table in bytes
      */
-    void streamTable(byte[] byteArray, int offset, int length) throws IOException;
+    void streamTable(byte[] ttfData, int offset, int size) throws IOException;
 }
diff --git a/src/java/org/apache/fop/render/ps/fonts/PSTTFGlyphOutputStream.java b/src/java/org/apache/fop/render/ps/fonts/PSTTFGlyphOutputStream.java
index 9727af764..1335a66b5 100644
--- a/src/java/org/apache/fop/render/ps/fonts/PSTTFGlyphOutputStream.java
+++ b/src/java/org/apache/fop/render/ps/fonts/PSTTFGlyphOutputStream.java
@@ -27,11 +27,12 @@ import org.apache.fop.fonts.truetype.TTFGlyphOutputStream;
  * This class streams glyphs from the "glyf" table in a True Type font.
  */
 public class PSTTFGlyphOutputStream implements TTFGlyphOutputStream {
+
     /** This counts the total number of bytes written that have been streamed. */
-    private int byteCounter = 0;
+    private int byteCounter;
 
     /** This is a place-holder for the offset of the last string boundary. */
-    private int lastStringBoundary = 0;
+    private int lastStringBoundary;
     private PSTTFGenerator ttfGen;
 
     /**
@@ -42,31 +43,29 @@ public class PSTTFGlyphOutputStream implements TTFGlyphOutputStream {
         this.ttfGen = ttfGen;
     }
 
-    /** {@inheritDoc} */
-    public void startGlyphStream()  throws IOException {
+    public void startGlyphStream() throws IOException {
         ttfGen.startString();
     }
 
-    /** {@inheritDoc} */
-    public void streamGlyph(byte[] byteArray, int offset, int length) throws IOException {
-        if (length > PSTTFGenerator.MAX_BUFFER_SIZE) {
-            throw new UnsupportedOperationException("The glyph is " + length + " there may be an "
-                    + "error in the font file.");
+    public void streamGlyph(byte[] glyphData, int offset, int size) throws IOException {
+        if (size > PSTTFGenerator.MAX_BUFFER_SIZE) {
+            throw new UnsupportedOperationException("The glyph is " + size
+                    + " bytes. There may be an error in the font file.");
         }
 
-        if (length + (byteCounter - lastStringBoundary) < PSTTFGenerator.MAX_BUFFER_SIZE) {
-            ttfGen.streamBytes(byteArray, offset, length);
+        if (size + (byteCounter - lastStringBoundary) < PSTTFGenerator.MAX_BUFFER_SIZE) {
+            ttfGen.streamBytes(glyphData, offset, size);
         } else {
             ttfGen.endString();
             lastStringBoundary = byteCounter;
             ttfGen.startString();
-            ttfGen.streamBytes(byteArray, offset, length);
+            ttfGen.streamBytes(glyphData, offset, size);
         }
-        byteCounter += length;
+        byteCounter += size;
     }
 
-    /** {@inheritDoc} */
     public void endGlyphStream() throws IOException {
         ttfGen.endString();
     }
+
 }
diff --git a/src/java/org/apache/fop/render/ps/fonts/PSTTFTableOutputStream.java b/src/java/org/apache/fop/render/ps/fonts/PSTTFTableOutputStream.java
index 24d96878e..431374709 100644
--- a/src/java/org/apache/fop/render/ps/fonts/PSTTFTableOutputStream.java
+++ b/src/java/org/apache/fop/render/ps/fonts/PSTTFTableOutputStream.java
@@ -28,7 +28,9 @@ import org.apache.fop.fonts.truetype.TTFTableOutputStream;
  *
  */
 public class PSTTFTableOutputStream implements TTFTableOutputStream  {
+
     private PSTTFGenerator ttfGen;
+
     /**
      * Constructor.
      * @param ttfGen PSGenerator the streamer class used for streaming bytes.
@@ -37,16 +39,15 @@ public class PSTTFTableOutputStream implements TTFTableOutputStream  {
         this.ttfGen = ttfGen;
     }
 
-    /** {@inheritDoc} */
-    public void streamTable(byte[] byteArray, int offset, int length) throws IOException {
+    public void streamTable(byte[] ttfData, int offset, int size) throws IOException {
         int offsetPosition = offset;
         // Need to split the table into MAX_BUFFER_SIZE chunks
-        for (int i = 0; i < length / PSTTFGenerator.MAX_BUFFER_SIZE; i++) {
-            streamString(byteArray, offsetPosition, PSTTFGenerator.MAX_BUFFER_SIZE);
+        for (int i = 0; i < size / PSTTFGenerator.MAX_BUFFER_SIZE; i++) {
+            streamString(ttfData, offsetPosition, PSTTFGenerator.MAX_BUFFER_SIZE);
             offsetPosition += PSTTFGenerator.MAX_BUFFER_SIZE;
         }
-        if (length % PSTTFGenerator.MAX_BUFFER_SIZE > 0) {
-            streamString(byteArray, offsetPosition, length % PSTTFGenerator.MAX_BUFFER_SIZE);
+        if (size % PSTTFGenerator.MAX_BUFFER_SIZE > 0) {
+            streamString(ttfData, offsetPosition, size % PSTTFGenerator.MAX_BUFFER_SIZE);
         }
     }