From 992889d0a8c427bf6ff2fa313699f13bd9f31094 Mon Sep 17 00:00:00 2001 From: Vincent Hennebert Date: Wed, 30 May 2012 15:28:14 +0000 Subject: [PATCH] Javadoc improvements git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/branches/Temp_TrueTypeInPostScript@1344309 13f79535-47bb-0310-9956-ffa450edef68 --- src/java/org/apache/fop/fonts/CustomFont.java | 8 +-- .../org/apache/fop/fonts/EmbedFontInfo.java | 2 +- .../org/apache/fop/fonts/EmbeddingMode.java | 12 ++-- src/java/org/apache/fop/fonts/FontType.java | 2 +- .../org/apache/fop/fonts/MutableFont.java | 4 +- .../apache/fop/fonts/truetype/TTFFile.java | 9 +-- .../fonts/truetype/TTFGlyphOutputStream.java | 18 ++--- .../fop/fonts/truetype/TTFOutputStream.java | 16 ++--- .../fop/fonts/truetype/TTFSubSetFile.java | 12 +--- .../fop/fonts/truetype/TTFTableName.java | 68 +++++++++---------- .../fonts/truetype/TTFTableOutputStream.java | 14 ++-- .../ps/fonts/PSTTFGlyphOutputStream.java | 27 ++++---- .../ps/fonts/PSTTFTableOutputStream.java | 13 ++-- 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(); 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); } } -- 2.39.5