From d275b3c2bda6ed2a5735e5e79eca25912fd2a485 Mon Sep 17 00:00:00 2001 From: "Andreas L. Delmelle" Date: Sat, 16 May 2015 02:10:42 +0000 Subject: [PATCH] Javadoc fixups git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@1679676 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/fop/afp/AFPResourceManager.java | 18 ++++++++------ .../org/apache/fop/afp/fonts/AFPFont.java | 1 - .../apache/fop/afp/fonts/CharacterSet.java | 16 +++++++++---- .../fop/afp/fonts/CharacterSetBuilder.java | 17 +++++++------ .../afp/fonts/CharacterSetOrientation.java | 24 +++++++++++++------ .../apache/fop/afp/fonts/DoubleByteFont.java | 4 ++-- .../fop/afp/fonts/FontRuntimeException.java | 1 - .../apache/fop/afp/fonts/FopCharacterSet.java | 2 +- .../org/apache/fop/afp/fonts/RasterFont.java | 7 +++--- .../fop/afp/modca/AbstractNamedAFPObject.java | 1 + .../apache/fop/afp/modca/IMImageObject.java | 1 - .../fop/afp/modca/TagLogicalElement.java | 1 - .../modca/triplets/AttributeValueTriplet.java | 1 - .../apache/fop/afp/svg/AFPBridgeContext.java | 1 + .../fop/afp/svg/AFPTextElementBridge.java | 4 ++-- .../apache/fop/afp/svg/AFPTextPainter.java | 1 + .../apache/fop/afp/util/AFPResourceUtil.java | 3 +-- .../fop/afp/util/DTDEntityResolver.java | 5 ++-- .../fop/afp/util/StructuredFieldReader.java | 3 +-- 19 files changed, 62 insertions(+), 49 deletions(-) diff --git a/src/java/org/apache/fop/afp/AFPResourceManager.java b/src/java/org/apache/fop/afp/AFPResourceManager.java index 6fa4a17b7..fc34925d2 100644 --- a/src/java/org/apache/fop/afp/AFPResourceManager.java +++ b/src/java/org/apache/fop/afp/AFPResourceManager.java @@ -74,6 +74,8 @@ public class AFPResourceManager { /** * Main constructor + * + * @param resourceResolver the associated {@link InternalResourceResolver} instance */ public AFPResourceManager(InternalResourceResolver resourceResolver) { this.factory = new Factory(); @@ -263,19 +265,21 @@ public class AFPResourceManager { } /** - * TODO - * @param resourceInfo - * @return + * Returns {@code true} if the passed {@link AFPResourceInfo} instance is already cached. + * + * @param resourceInfo the resource info to check + * @return {@code true} if the object is cached */ public boolean isObjectCached(AFPResourceInfo resourceInfo) { return includeObjectCache.containsKey(resourceInfo); } /** - * TODO - * @param resourceInfo - * @param areaInfo - * @return + * {@asf.todo} + * + * @param resourceInfo the resource info to check + * @param areaInfo the area info to check + * @return {@code true} if ... */ public boolean includeCachedObject(AFPResourceInfo resourceInfo, AFPObjectAreaInfo areaInfo) { diff --git a/src/java/org/apache/fop/afp/fonts/AFPFont.java b/src/java/org/apache/fop/afp/fonts/AFPFont.java index 3c84e4aa9..720914bf4 100644 --- a/src/java/org/apache/fop/afp/fonts/AFPFont.java +++ b/src/java/org/apache/fop/afp/fonts/AFPFont.java @@ -31,7 +31,6 @@ import org.apache.fop.fonts.Typeface; /** * All implementations of AFP fonts should extend this base class, * the object implements the FontMetrics information. - *

*/ public abstract class AFPFont extends Typeface { diff --git a/src/java/org/apache/fop/afp/fonts/CharacterSet.java b/src/java/org/apache/fop/afp/fonts/CharacterSet.java index 3df8ba4c4..d57b14ed7 100644 --- a/src/java/org/apache/fop/afp/fonts/CharacterSet.java +++ b/src/java/org/apache/fop/afp/fonts/CharacterSet.java @@ -38,16 +38,16 @@ import org.apache.fop.afp.util.StringUtils; * font description information for identifying the characters, font metric * information for positioning the characters, and character shape information * for presenting the character images. - *

+ *
* Presenting a graphic character on a presentation surface requires * information on the rotation and position of character on the physical * or logical page. - *

+ *
* This class proivdes font metric information for a particular font * as identified by the character set name. This information is obtained * directly from the AFP font files which must be installed in the path * specified in the afp-fonts xml definition file. - *

+ *
*/ public class CharacterSet { @@ -167,14 +167,18 @@ public class CharacterSet { } /** - * TODO + * Return the width to use for an underscore (_) character. + * + * @return the width of an underscore character */ public int getUnderscoreWidth() { return getCharacterSetOrientation().getUnderscoreWidth(); } /** - * TODO + * Return the position for an underscore (_) character. + * + * @return the position of an underscore character */ public int getUnderscorePosition() { return getCharacterSetOrientation().getUnderscorePosition(); @@ -226,6 +230,7 @@ public class CharacterSet { * identified by the parameter passed. * * @param character the Unicode character from which the width will be calculated + * @param size the font size * @return the width of the character */ public int getWidth(char character, int size) { @@ -255,6 +260,7 @@ public class CharacterSet { try { nameBytes = name.getBytes(AFPConstants.EBCIDIC_ENCODING); } catch (UnsupportedEncodingException usee) { + // @SuppressFBWarnings("DM_DEFAULT_ENCODING") nameBytes = name.getBytes(); LOG.warn( "UnsupportedEncodingException translating the name " + name); diff --git a/src/java/org/apache/fop/afp/fonts/CharacterSetBuilder.java b/src/java/org/apache/fop/afp/fonts/CharacterSetBuilder.java index 6f19c64d5..e7b9041ba 100644 --- a/src/java/org/apache/fop/afp/fonts/CharacterSetBuilder.java +++ b/src/java/org/apache/fop/afp/fonts/CharacterSetBuilder.java @@ -46,9 +46,9 @@ import org.apache.fop.fonts.Typeface; /** * The CharacterSetBuilder is responsible building the a CharacterSet instance that holds - * the font metric data. The data is either read from disk and passed to a CharacterSet (*) - * or a FopCharacterSet is instantiated that is composed of a Typeface instance configured - * with this data.

+ * the font metric data. The data is either read from disk and passed to a CharacterSet (*) + * or a FopCharacterSet is instantiated that is composed of a Typeface instance configured + * with this data.
* -*- For referenced fonts CharacterSetBuilder is responsible for reading the font attributes * from binary code page files and the character set metric files. In IBM font structure, a * code page maps each character of text to the characters in a character set. @@ -58,11 +58,10 @@ import org.apache.fop.fonts.Typeface; * outline pattern) of the character in the character set specified. The image * in the character set is the image that is printed in the document. To be a * valid code page for a particular character set, all character IDs in the code - * page must be included in that character set.

This class will read the - * font information from the binary code page files and character set metric - * files in order to determine the correct metrics to use when rendering the - * formatted object.

- * + * page must be included in that character set.
+ * This class will read the font information from the binary code page files and character + * set metric files in order to determine the correct metrics to use when rendering the + * formatted object. */ public abstract class CharacterSetBuilder { @@ -139,7 +138,7 @@ public abstract class CharacterSetBuilder { /** * Returns an InputStream to a given file path and filename * - * * @param accessor the resource accessor + * @param accessor the resource accessor * @param uriStr the URI * @param eventProducer for handling AFP related events * @return an inputStream diff --git a/src/java/org/apache/fop/afp/fonts/CharacterSetOrientation.java b/src/java/org/apache/fop/afp/fonts/CharacterSetOrientation.java index 5fe524536..6860e93a8 100644 --- a/src/java/org/apache/fop/afp/fonts/CharacterSetOrientation.java +++ b/src/java/org/apache/fop/afp/fonts/CharacterSetOrientation.java @@ -26,19 +26,18 @@ import java.awt.Rectangle; * of character shapes by defining their characteristics, which include * Font-Description information for identifying the characters, Font-Metric * information for positioning the characters, and Character-Shape - * information for presenting the character images. + * information for presenting the character images.
* * Presenting a graphic character on a presentation surface requires * that you communicate this information clearly to rotate and position - * characters correctly on the physical or logical page. + * characters correctly on the physical or logical page.
* * This class provides font metric information for a particular font - * as by the orientation. + * as by the orientation.
* * This information is obtained directly from the AFP font files which must * be installed in the classpath under in the location specified by the path * attribute in the afp-font.xml file. - *

*/ public class CharacterSetOrientation { @@ -83,7 +82,11 @@ public class CharacterSetOrientation { /** * Constructor for the CharacterSetOrientation, the orientation is * expressed as the degrees rotation (i.e 0, 90, 180, 270) - * @param orientation the character set orientation + * + * @param orientation the character set orientation + * @param spaceIncrement the space increment + * @param emSpaceIncrement the em space increment + * @param nomCharIncrement the nominal character increment */ public CharacterSetOrientation(int orientation, int spaceIncrement, int emSpaceIncrement, int nomCharIncrement) { @@ -131,14 +134,18 @@ public class CharacterSetOrientation { } /** - * TODO + * {@asf.todo} + * + * @return the underscore width */ public int getUnderscoreWidth() { return underscoreWidth; } /** - * TODO + * {@asf.todo} + * + * @return the underscore position */ public int getUnderscorePosition() { return underscorePosition; @@ -165,6 +172,7 @@ public class CharacterSetOrientation { * Get the width (in 1/1000ths of a point size) of the character * identified by the parameter passed. * @param character the Unicode character to evaluate + * @param size the font size * @return the widths of the character */ public int getWidth(char character, int size) { @@ -180,6 +188,7 @@ public class CharacterSetOrientation { * Get the character box (rectangle with dimensions in 1/1000ths of a point size) of the character * identified by the parameter passed. * @param character the Unicode character to evaluate + * @param size the font size * @return the character box */ public Rectangle getCharacterBox(char character, int size) { @@ -258,6 +267,7 @@ public class CharacterSetOrientation { * identified by the parameter passed. * @param character the Unicode character for which the width is being set * @param width the widths of the character + * @param characterBox the character box */ public void setCharacterMetrics(char character, int width, Rectangle characterBox) { characterMetrics.put((int) character, new CharacterMetrics(width, characterBox)); diff --git a/src/java/org/apache/fop/afp/fonts/DoubleByteFont.java b/src/java/org/apache/fop/afp/fonts/DoubleByteFont.java index 5b9bf6101..b023b48a6 100644 --- a/src/java/org/apache/fop/afp/fonts/DoubleByteFont.java +++ b/src/java/org/apache/fop/afp/fonts/DoubleByteFont.java @@ -30,10 +30,10 @@ import org.apache.commons.logging.LogFactory; import org.apache.fop.afp.AFPEventProducer; /** - * Implementation of AbstractOutlineFont that supports double-byte fonts (CID Keyed font (Type 0)). + * Implementation of {@link AbstractOutlineFont} that supports double-byte fonts (CID Keyed font (Type 0)). * The width of characters that are not prescribed a width metrics in the font resource use * a fallback width. The default width is 1 em. A character can be supplied and queried for the - * fallback width of all non-ideograph characters.

+ * fallback width of all non-ideograph characters. */ public class DoubleByteFont extends AbstractOutlineFont { diff --git a/src/java/org/apache/fop/afp/fonts/FontRuntimeException.java b/src/java/org/apache/fop/afp/fonts/FontRuntimeException.java index 86e41707f..20bbc9d5b 100644 --- a/src/java/org/apache/fop/afp/fonts/FontRuntimeException.java +++ b/src/java/org/apache/fop/afp/fonts/FontRuntimeException.java @@ -21,7 +21,6 @@ package org.apache.fop.afp.fonts; /** * A runtime exception for handling fatal errors in processing fonts. - *

*/ public class FontRuntimeException extends RuntimeException { diff --git a/src/java/org/apache/fop/afp/fonts/FopCharacterSet.java b/src/java/org/apache/fop/afp/fonts/FopCharacterSet.java index b1210c6c1..d3af78f7b 100644 --- a/src/java/org/apache/fop/afp/fonts/FopCharacterSet.java +++ b/src/java/org/apache/fop/afp/fonts/FopCharacterSet.java @@ -26,7 +26,7 @@ import org.apache.fop.afp.util.AFPResourceAccessor; import org.apache.fop.fonts.Typeface; /** - * A Character set for a normal FOP font

+ * A Character set for a normal FOP font */ public class FopCharacterSet extends CharacterSet { diff --git a/src/java/org/apache/fop/afp/fonts/RasterFont.java b/src/java/org/apache/fop/afp/fonts/RasterFont.java index 7a5107d04..b587ef3cd 100644 --- a/src/java/org/apache/fop/afp/fonts/RasterFont.java +++ b/src/java/org/apache/fop/afp/fonts/RasterFont.java @@ -32,8 +32,7 @@ import org.apache.commons.logging.LogFactory; * A font where each character is stored as an array of pixels (a bitmap). Such * fonts are not easily scalable, in contrast to vectored fonts. With this type * of font, the font metrics information is held in character set files (one for - * each size and style).

- * + * each size and style). */ public class RasterFont extends AFPFont { @@ -49,8 +48,8 @@ public class RasterFont extends AFPFont { * Constructor for the raster font requires the name, weight and style * attribute to be available as this forms the key to the font. * - * @param name - * the name of the font + * @param name the name of the font + * @param embeddable {@code true} if the font is embeddable */ public RasterFont(String name, boolean embeddable) { super(name, embeddable); diff --git a/src/java/org/apache/fop/afp/modca/AbstractNamedAFPObject.java b/src/java/org/apache/fop/afp/modca/AbstractNamedAFPObject.java index 0d1b7bc7e..f92a26851 100644 --- a/src/java/org/apache/fop/afp/modca/AbstractNamedAFPObject.java +++ b/src/java/org/apache/fop/afp/modca/AbstractNamedAFPObject.java @@ -82,6 +82,7 @@ public abstract class AbstractNamedAFPObject extends AbstractTripletStructuredOb try { nameBytes = name.getBytes(AFPConstants.EBCIDIC_ENCODING); } catch (UnsupportedEncodingException usee) { + // @SuppressFBWarnings("DM_DEFAULT_ENCODING") nameBytes = name.getBytes(); LOG.warn( "Constructor:: UnsupportedEncodingException translating the name " diff --git a/src/java/org/apache/fop/afp/modca/IMImageObject.java b/src/java/org/apache/fop/afp/modca/IMImageObject.java index cf9363f33..a0fa763dc 100644 --- a/src/java/org/apache/fop/afp/modca/IMImageObject.java +++ b/src/java/org/apache/fop/afp/modca/IMImageObject.java @@ -38,7 +38,6 @@ import org.apache.fop.afp.ioca.ImageRasterData; * structured field that defines the position of the image cell relative to * the origin of the entire image. Each ICP also specifies the size of the * image cell and a fill rectangle into which the cell is replicated. - *

*/ public class IMImageObject extends AbstractNamedAFPObject { diff --git a/src/java/org/apache/fop/afp/modca/TagLogicalElement.java b/src/java/org/apache/fop/afp/modca/TagLogicalElement.java index 9ae88b46f..dbd402335 100644 --- a/src/java/org/apache/fop/afp/modca/TagLogicalElement.java +++ b/src/java/org/apache/fop/afp/modca/TagLogicalElement.java @@ -45,7 +45,6 @@ import org.apache.fop.afp.util.BinaryUtils; * embedded in, the same page or page group. The Tag Logical Element structured * field does not provide any presentation specifications and therefore has no * effect on the appearance of a document when it is presented. - *

*/ public class TagLogicalElement extends AbstractTripletStructuredObject { diff --git a/src/java/org/apache/fop/afp/modca/triplets/AttributeValueTriplet.java b/src/java/org/apache/fop/afp/modca/triplets/AttributeValueTriplet.java index ec2ae8d7c..1c10a1ed0 100644 --- a/src/java/org/apache/fop/afp/modca/triplets/AttributeValueTriplet.java +++ b/src/java/org/apache/fop/afp/modca/triplets/AttributeValueTriplet.java @@ -53,7 +53,6 @@ public class AttributeValueTriplet extends AbstractTriplet { try { tleByteValue = attVal.getBytes(AFPConstants.EBCIDIC_ENCODING); } catch (UnsupportedEncodingException usee) { - tleByteValue = attVal.getBytes(); throw new IllegalArgumentException(attVal + " encoding failed"); } System.arraycopy(tleByteValue, 0, data, 4, tleByteValue.length); diff --git a/src/java/org/apache/fop/afp/svg/AFPBridgeContext.java b/src/java/org/apache/fop/afp/svg/AFPBridgeContext.java index 1e8f2b606..183a07ab6 100644 --- a/src/java/org/apache/fop/afp/svg/AFPBridgeContext.java +++ b/src/java/org/apache/fop/afp/svg/AFPBridgeContext.java @@ -57,6 +57,7 @@ public class AFPBridgeContext extends AbstractFOPBridgeContext { * @param linkTransform AffineTransform to properly place links, * may be null * @param g2d an AFPGraphics 2D implementation + * @param eventBroadCaster the associated event broadcaster */ public AFPBridgeContext(UserAgent userAgent, FontInfo fontInfo, ImageManager imageManager, ImageSessionContext imageSessionContext, diff --git a/src/java/org/apache/fop/afp/svg/AFPTextElementBridge.java b/src/java/org/apache/fop/afp/svg/AFPTextElementBridge.java index efc26eda3..d7de961e7 100644 --- a/src/java/org/apache/fop/afp/svg/AFPTextElementBridge.java +++ b/src/java/org/apache/fop/afp/svg/AFPTextElementBridge.java @@ -24,14 +24,14 @@ import org.apache.batik.bridge.TextPainter; import org.apache.fop.svg.AbstractFOPTextElementBridge; /** - * Bridge class for the <text> element. + * Bridge class for the <text> element. * This bridge will use the direct text painter if the text * for the element is simple. */ public class AFPTextElementBridge extends AbstractFOPTextElementBridge { /** - * Constructs a new bridge for the <text> element. + * Constructs a new bridge for the <text> element. * * @param textPainter the text painter to use */ diff --git a/src/java/org/apache/fop/afp/svg/AFPTextPainter.java b/src/java/org/apache/fop/afp/svg/AFPTextPainter.java index 3cc377034..971a381f4 100644 --- a/src/java/org/apache/fop/afp/svg/AFPTextPainter.java +++ b/src/java/org/apache/fop/afp/svg/AFPTextPainter.java @@ -41,6 +41,7 @@ public class AFPTextPainter extends AbstractFOPTextPainter { /** * Create a new text painter with the given font information. * @param nativeTextHandler the NativeTextHandler instance used for text painting + * @param fopFontFamilyResolver the font resolver */ public AFPTextPainter(FOPTextHandler nativeTextHandler, FontFamilyResolver fopFontFamilyResolver) { super(nativeTextHandler, new FOPStrokingTextPainter(fopFontFamilyResolver)); diff --git a/src/java/org/apache/fop/afp/util/AFPResourceUtil.java b/src/java/org/apache/fop/afp/util/AFPResourceUtil.java index 98d2a8f8a..7972d7c76 100644 --- a/src/java/org/apache/fop/afp/util/AFPResourceUtil.java +++ b/src/java/org/apache/fop/afp/util/AFPResourceUtil.java @@ -46,13 +46,12 @@ import org.apache.fop.afp.parser.UnparsedStructuredField; * components and to provide commands and information to applications using * the data. Structured fields may contain one or more parameters. Each * parameter provides one value from a set of values defined by the architecture. - *

+ *
* MO:DCA structured fields consist of two parts: an introducer that identifies * the length and type of the structured field, and data that provides the * structured field's effect. The data is contained in a set of parameters, * which can consist of other data structures and data elements. The maximum * length of a structured field is 32767 bytes. - *

*/ public final class AFPResourceUtil { diff --git a/src/java/org/apache/fop/afp/util/DTDEntityResolver.java b/src/java/org/apache/fop/afp/util/DTDEntityResolver.java index 8df25a1cc..2df7346c7 100644 --- a/src/java/org/apache/fop/afp/util/DTDEntityResolver.java +++ b/src/java/org/apache/fop/afp/util/DTDEntityResolver.java @@ -28,11 +28,10 @@ import org.xml.sax.InputSource; import org.apache.fop.afp.fonts.FontRuntimeException; /** - * An entity resolver for both DOM and SAX models of the SAX document. - *

+ * An entity resolver for both DOM and SAX models of the SAX document.
* The entity resolver only handles queries for the DTD. It will find any URI * with a recognised public id and return an {@link org.xml.sax.InputSource}. - *

+ *
* *

This work was authored by Joe Schmetzer (joe@exubero.com).

*/ diff --git a/src/java/org/apache/fop/afp/util/StructuredFieldReader.java b/src/java/org/apache/fop/afp/util/StructuredFieldReader.java index b20e1579f..6180da67a 100644 --- a/src/java/org/apache/fop/afp/util/StructuredFieldReader.java +++ b/src/java/org/apache/fop/afp/util/StructuredFieldReader.java @@ -30,13 +30,12 @@ import java.io.InputStream; * components and to provide commands and information to applications using * the data. Structured fields may contain one or more parameters. Each * parameter provides one value from a set of values defined by the architecture. - *

+ *
* MO:DCA structured fields consist of two parts: an introducer that identifies * the length and type of the structured field, and data that provides the * structured field's effect. The data is contained in a set of parameters, * which can consist of other data structures and data elements. The maximum * length of a structured field is 32767 bytes. - *

*/ public class StructuredFieldReader { -- 2.39.5