Javadoc improvements

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

5 files changed, 34 insertions, 35 deletions

diff --git a/src/java/org/apache/fop/render/ps/fonts/PSTTFGenerator.java b/src/java/org/apache/fop/render/ps/fonts/PSTTFGenerator.java
index f8ce37505..31035dc31 100644
--- a/src/java/org/apache/fop/render/ps/fonts/PSTTFGenerator.java
+++ b/src/java/org/apache/fop/render/ps/fonts/PSTTFGenerator.java
@@ -26,7 +26,7 @@ import org.apache.xmlgraphics.util.io.ASCIIHexOutputStream;
 
 /**
  * This is a wrapper for {@link PSGenerator} that contains some members specific for streaming
- * True Type fonts to a PostScript document.
+ * TrueType fonts to a PostScript document.
  */
 public class PSTTFGenerator {
     private PSGenerator gen;
@@ -40,8 +40,8 @@ public class PSTTFGenerator {
     public static final int MAX_BUFFER_SIZE = 32764;
 
     /**
-     * Constructor - initialises the PSGenerator in this wrapper class.
-     * @param gen PSGenerator
+     * Creates a new instance wrapping the given generator.
+     * @param gen the PSGenerator to wrap
      */
     public PSTTFGenerator(PSGenerator gen) {
         this.gen = gen;
@@ -49,8 +49,7 @@ public class PSTTFGenerator {
     }
 
     /**
-     * Begins writing a string by writing '<' to the begin.
-     * @throws IOException file write exception.
+     * Writes the '&lt;' character that starts a string.
      */
     public void startString() throws IOException {
         // We need to reset the streamer so that it starts a new line in the PS document
@@ -59,31 +58,29 @@ public class PSTTFGenerator {
     }
 
     /**
-     * Streams a string to a PostScript document (wraps PSGenerator.write(String)).
-     * @param cmd String
-     * @throws IOException file write exception
+     * Writes the given string to the output.
+     * @param cmd a string
      */
     public void write(String cmd) throws IOException {
         gen.write(cmd);
     }
 
     /**
-     * Streams a string followed by a new line char to a PostScript document (wraps
-     * PSGenerator.writeln(String)).
-     * @param cmd String
-     * @throws IOException file write exception
+     * Writes the given string to the output, followed by a newline.
+     * @param cmd a string
      */
     public void writeln(String cmd) throws IOException {
         gen.writeln(cmd);
     }
 
     /**
-     * Streams the bytes.
-     * @param byteArray byte[] the byte array to stream to file.
-     * @param offset int the starting position in the byte array to stream to file.
-     * @param length the number of bytes to stream to file. This MUST be less than
-     * MAX_BUFFER_SIZE - 1 since strings are suffixed by '00' (as in spec).
-     * @throws IOException file write exception
+     * Writes bytes from the given byte array to the output.
+     *
+     * @param byteArray byte[] a byte array
+     * @param offset the position in the byte array where the streaming must start
+     * @param length the number of bytes to stream. This MUST be less than
+     * {@link MAX_BUFFER_SIZE} - 1 since strings are suffixed by '00' (see Section 4.2 of
+     * Adobe Technical Note #5012, <em>The Type 42 Font Format Specification</em>.).
      */
     public void streamBytes(byte[] byteArray, int offset, int length) throws IOException {
         if (length > MAX_BUFFER_SIZE) {
@@ -95,10 +92,10 @@ public class PSTTFGenerator {
 
     /**
      * Finishes writing a string by appending '00' and '>' to the end.
-     * @throws IOException file write exception
      */
     public void endString() throws IOException {
         /* Appends a '00' to the end of the string as specified in the spec */
         gen.write("00\n> ");
     }
+
 }
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 1335a66b5..cc2ae3e82 100644
--- a/src/java/org/apache/fop/render/ps/fonts/PSTTFGlyphOutputStream.java
+++ b/src/java/org/apache/fop/render/ps/fonts/PSTTFGlyphOutputStream.java
@@ -24,15 +24,19 @@ import java.io.IOException;
 import org.apache.fop.fonts.truetype.TTFGlyphOutputStream;
 
 /**
- * This class streams glyphs from the "glyf" table in a True Type font.
+ * Streams glyphs in accordance with the constraints of the PostScript file format.
+ * Mainly, PostScript strings have a limited capacity and the font data may have to be
+ * broken down into several strings; however, this must occur at well-defined places like
+ * table or glyph boundaries. See also Adobe Technical Note #5012, <em>The Type 42 Font
+ * Format Specification</em>.
  */
 public class PSTTFGlyphOutputStream implements TTFGlyphOutputStream {
 
-    /** This counts the total number of bytes written that have been streamed. */
+    /** Total number of bytes written so far. */
     private int byteCounter;
 
-    /** This is a place-holder for the offset of the last string boundary. */
     private int lastStringBoundary;
+
     private PSTTFGenerator ttfGen;
 
     /**
diff --git a/src/java/org/apache/fop/render/ps/fonts/PSTTFOutputStream.java b/src/java/org/apache/fop/render/ps/fonts/PSTTFOutputStream.java
index bf3803eb4..271d87d1b 100644
--- a/src/java/org/apache/fop/render/ps/fonts/PSTTFOutputStream.java
+++ b/src/java/org/apache/fop/render/ps/fonts/PSTTFOutputStream.java
@@ -21,42 +21,40 @@ package org.apache.fop.render.ps.fonts;
 
 import java.io.IOException;
 
+import org.apache.xmlgraphics.ps.PSGenerator;
+
 import org.apache.fop.fonts.truetype.TTFGlyphOutputStream;
 import org.apache.fop.fonts.truetype.TTFOutputStream;
 import org.apache.fop.fonts.truetype.TTFTableOutputStream;
-import org.apache.xmlgraphics.ps.PSGenerator;
 
 /**
- * Implements TTFOutputStream and streams font tables to a PostScript file.
+ * Streams a TrueType font according to the PostScript format.
  */
 public class PSTTFOutputStream implements TTFOutputStream {
-    /** The wrapper class for PSGenerator */
+
     private final PSTTFGenerator ttfGen;
 
     /**
-     * Constructor - assigns a PSGenerator to stream the font.
-     * @param gen PSGenerator.
+     * Creates a new instance wrapping the given generator.
+     *
+     * @param gen the generator to wrap
      */
     public PSTTFOutputStream(PSGenerator gen) {
         this.ttfGen = new PSTTFGenerator(gen);
     }
 
-    /** {@inheritDoc} */
     public void startFontStream() throws IOException {
         ttfGen.write("/sfnts[");
     }
 
-    /** {@inheritDoc} */
     public TTFTableOutputStream getTableOutputStream() {
         return new PSTTFTableOutputStream(ttfGen);
     }
 
-    /** {@inheritDoc} */
     public TTFGlyphOutputStream getGlyphOutputStream() {
         return new PSTTFGlyphOutputStream(ttfGen);
     }
 
-    /** {@inheritDoc} */
     public void endFontStream() throws IOException {
         ttfGen.writeln("] def");
     }
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 431374709..2226e11e8 100644
--- a/src/java/org/apache/fop/render/ps/fonts/PSTTFTableOutputStream.java
+++ b/src/java/org/apache/fop/render/ps/fonts/PSTTFTableOutputStream.java
@@ -24,8 +24,7 @@ import java.io.IOException;
 import org.apache.fop.fonts.truetype.TTFTableOutputStream;
 
 /**
- * This class streams a truetype table to a PostScript file.
- *
+ * Streams a TrueType table according to the PostScript format.
  */
 public class PSTTFTableOutputStream implements TTFTableOutputStream  {
 
@@ -33,7 +32,7 @@ public class PSTTFTableOutputStream implements TTFTableOutputStream  {
 
     /**
      * Constructor.
-     * @param ttfGen PSGenerator the streamer class used for streaming bytes.
+     * @param ttfGen the helper object to stream TrueType data
      */
     public PSTTFTableOutputStream(PSTTFGenerator ttfGen) {
         this.ttfGen = ttfGen;
@@ -56,4 +55,5 @@ public class PSTTFTableOutputStream implements TTFTableOutputStream  {
         ttfGen.streamBytes(byteArray, offset, length);
         ttfGen.endString();
     }
+
 }
diff --git a/src/java/org/apache/fop/util/HexEncoder.java b/src/java/org/apache/fop/util/HexEncoder.java
index 38f312784..9ca91f2d2 100644
--- a/src/java/org/apache/fop/util/HexEncoder.java
+++ b/src/java/org/apache/fop/util/HexEncoder.java
@@ -20,7 +20,7 @@
 package org.apache.fop.util;
 
 /**
- * A helper class create to hex-encoded representations of numbers.
+ * A helper class to create hex-encoded representations of numbers.
  */
 public final class HexEncoder {