From 86004ef152f37a9046c3a9be34190e8852b1e736 Mon Sep 17 00:00:00 2001 From: Vincent Hennebert Date: Thu, 31 May 2012 15:24:51 +0000 Subject: [PATCH] Javadoc improvements git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/branches/Temp_TrueTypeInPostScript@1344773 13f79535-47bb-0310-9956-ffa450edef68 --- .../fop/render/ps/fonts/PSTTFGenerator.java | 35 +++++++++---------- .../ps/fonts/PSTTFGlyphOutputStream.java | 10 ++++-- .../render/ps/fonts/PSTTFOutputStream.java | 16 ++++----- .../ps/fonts/PSTTFTableOutputStream.java | 6 ++-- src/java/org/apache/fop/util/HexEncoder.java | 2 +- 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 '<' 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, The Type 42 Font Format Specification.). */ 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, The Type 42 Font + * Format Specification. */ 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 { -- 2.39.5