[PDFBOX-1897] fixing errors in javadoc comments

git-svn-id: https://svn.apache.org/repos/asf/pdfbox/trunk@1566286 13f79535-47bb-0310-9956-ffa450edef68

pdfbox/src/main/java/org/apache/pdfbox/pdfparser/BaseParser.java

@@ -1604,7 +1604,7 @@ protected void skipSpaces() throws IOException
     /**
      * This will read a long from the Stream and throw an {@link IllegalArgumentException} if the long value
      * has more than 10 digits (i.e. : bigger than {@link #OBJECT_NUMBER_THRESHOLD})
-     * @return
+     * @return the object number being read.
      * @throws IOException
      */
     protected long readObjectNumber() throws IOException
@@ -1619,7 +1619,7 @@ protected long readObjectNumber() throws IOException
     /**
      * This will read a integer from the Stream and throw an {@link IllegalArgumentException} if the integer value
      * has more than the maximum object revision (i.e. : bigger than {@link #GENERATION_NUMBER_THRESHOLD})
-     * @return
+     * @return the generation number being read.
      * @throws IOException
      */
     protected int readGenerationNumber() throws IOException

pdfbox/src/main/java/org/apache/pdfbox/pdfparser/ConformingPDFParser.java

@@ -55,7 +55,7 @@ public class ConformingPDFParser extends BaseParser {
     /**
      * Constructor.
      *
-     * @param input The input stream that contains the PDF document.
+     * @param inputFile The input stream that contains the PDF document.
      *
      * @throws IOException If there is an error initializing the stream.
      */
@@ -365,7 +365,7 @@ public COSBase getObject(long objectNumber, long generation) throws IOException
      * exception will be thrown.
      * @param objectNumber the object number you expect to read
      * @param generation the generation you expect this object to be
-     * @return
+     * @return the object being read.
      */
     public COSBase readObject(long objectNumber, long generation) throws IOException {
         // when recursivly reading, we always pull the object from the filesystem
@@ -598,7 +598,6 @@ protected COSDictionary readDictionaryBackwards() throws IOException {
      * backwards until it finds a newline.  This should only be used if we are
      * certain that the data will only be text, and not binary data.
      * 
-     * @param offset the location of the file where we should start reading
      * @return the string which was read
      * @throws IOException if there was an error reading data from the file
      */
@@ -629,7 +628,6 @@ protected String readLineBackwards() throws IOException {
      * This will read a line starting with the byte at offset and going
      * forward until it finds a newline.  This should only be used if we are
      * certain that the data will only be text, and not binary data.
-     * @param offset the location of the file where we should start reading
      * @return the string which was read
      * @throws IOException if there was an error reading data from the file
      */

pdfbox/src/main/java/org/apache/pdfbox/pdfparser/PDFStreamParser.java

@@ -153,7 +153,9 @@ public List<Object> getTokens()
     }
 
     /**
-     * {@inheritDoc}
+     * This will close the underlying pdfSource object.
+     * 
+     * @throws IOException If there is an error releasing resources.
      */
     public void close() throws IOException
     {

pdfbox/src/main/java/org/apache/pdfbox/pdfparser/VisualSignatureParser.java

@@ -50,7 +50,9 @@ public VisualSignatureParser(InputStream input) throws IOException
     }
 
     /**
-     * {@inheritDoc}
+     * This will parse the tokens making up the visual signature.
+     *
+     * @throws IOException If there is an error while parsing the visual signature.
      */
     public void parse() throws IOException 
     {

pdfbox/src/main/java/org/apache/pdfbox/pdfparser/XrefTrailerResolver.java

@@ -42,13 +42,13 @@
  * XRef/trailer objects are used to create xref table / trailer dictionary
  * in order they occur.
  *
- * For each new xref object/XRef stream method {@link #nextXrefObj(int)}
+ * For each new xref object/XRef stream method {@link #nextXrefObj(long, XRefType)}
  * must be called with start byte position. All following calls to
- * {@link #setXRef(COSObjectKey, int)} or {@link #setTrailer(COSDictionary)}
+ * {@link #setXRef(COSObjectKey, long)} or {@link #setTrailer(COSDictionary)}
  * will add the data for this byte position.
  *
  * After all objects are parsed the startxref position must be provided
- * using {@link #setStartxref(int)}. This is used to build the chain of
+ * using {@link #setStartxref(long)}. This is used to build the chain of
  * active xref/trailer objects used for creating document trailer and xref table.
  *
  * @author Timo Böhme (timo.boehme at ontochem.com)
@@ -293,7 +293,7 @@ public void setStartxref( long startxrefBytePosValue )
 
     /**
      * Gets the resolved trailer. Might return <code>null</code> in case
-     * {@link #setStartxref(int)} was not called before.
+     * {@link #setStartxref(long)} was not called before.
      *
      * @return the trailer if available
      */
@@ -304,7 +304,7 @@ public COSDictionary getTrailer()
 
     /**
      * Gets the resolved xref table. Might return <code>null</code> in case
-     *  {@link #setStartxref(int)} was not called before.
+     *  {@link #setStartxref(long)} was not called before.
      *
      * @return the xrefTable if available
      */

pdfbox/src/main/java/org/apache/pdfbox/pdfviewer/PageDrawer.java

@@ -814,7 +814,7 @@ public void drawImage(Image awtImage, AffineTransform at)
      * 
      * @throws IOException If there is an IO error while shade-filling the path/clipping area.
      * 
-     * @deprecated use {@link #shFill(COSName)) instead.
+     * @deprecated use {@link #shFill(COSName)} instead.
      */
     public void SHFill(COSName ShadingName) throws IOException
     {

pdfbox/src/main/java/org/apache/pdfbox/pdfwriter/COSStandardOutputStream.java

@@ -92,9 +92,8 @@ public long getPos()
     }
 
     /**
-     * This will get the current position in the stream.
+     * This will set the current position in the stream.
      *
-     * @return The current position in the stream.
      * @throws IOException 
      */
     public void setPos(long pos) throws IOException

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/ConformingPDDocument.java

@@ -73,7 +73,6 @@ public COSBase getObjectFromPool(COSObjectKey key) throws IOException {
 
     /**
      * This will get an object from the pool.
-     * @param key The object key.
      * @return The object in the pool or a new one if it has not been parsed yet.
      * @throws IOException If there is an error getting the proxy object.
      */

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocumentInformation.java

@@ -34,6 +34,8 @@
  * method then it will clear the value.
  *
  * @author <a href="mailto:[email protected]">Ben Litchfield</a>
+ * @author  Gerardo Ortiz
+ *
  * @version $Revision: 1.12 $
  */
 public class PDDocumentInformation implements COSObjectable
@@ -275,8 +277,6 @@ public Set<String> getMetadataKeys()
      * @param fieldName Name of custom metadata field from pdf document.
      *
      * @return String Value of metadata field
-     *
-     * @author  Gerardo Ortiz
      */
     public String getCustomMetadataValue(String fieldName)
     {

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDResources.java

@@ -44,6 +44,7 @@
  * This represents a set of resources available at the page/pages/stream level.
  * 
  * @author <a href="mailto:[email protected]">Ben Litchfield</a>
+ * @author By BM
  * 
  */
 public class PDResources implements COSObjectable
@@ -266,7 +267,6 @@ public Map<String, PDXObject> getXObjects()
      * This will get the map of images. An empty map will be returned if there are no underlying images. So far the keys
      * are COSName of the image and the value is the corresponding PDXObjectImage.
      * 
-     * @author By BM
      * @return The map of images.
      * @throws IOException If there is an error writing the picture.
      * 

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/common/COSArrayList.java

@@ -94,7 +94,7 @@ public COSArrayList( E actualObject, COSBase item, COSDictionary dictionary, COS
     }
 
     /**
-     * @deprecated use the {@link #COSArrayList(E, COSBase, COSDictionary, COSName)} method instead
+     * @deprecated use the {@link #COSArrayList(Object, COSBase, COSDictionary, COSName)} method instead
      */
     public COSArrayList( E actualObject, COSBase item, COSDictionary dictionary, String dictionaryKey )
     {

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/common/PDPageLabels.java

@@ -53,12 +53,12 @@ public class PDPageLabels implements COSObjectable
      * <p>
      * Note that the page label dictionary won't be automatically added to the
      * document; you will still need to do it manually (see
-     * {@link PDDocumentCatalog#setPageLabels(PDPageLabels)}.
+     * {@link org.apache.pdfbox.pdmodel.PDDocumentCatalog#setPageLabels(PDPageLabels)}.
      * </p>
      * 
      * @param document
      *            The document the page label dictionary is created for.
-     * @see PDDocumentCatalog#setPageLabels(PDPageLabels)
+     * @see org.apache.pdfbox.pdmodel.PDDocumentCatalog#setPageLabels(PDPageLabels)
      */
     public PDPageLabels(PDDocument document)
     {
@@ -76,14 +76,14 @@ public PDPageLabels(PDDocument document)
      * <p>
      * Note that the page label dictionary won't be automatically added to the
      * document; you will still need to do it manually (see
-     * {@link PDDocumentCatalog#setPageLabels(PDPageLabels)}.
+     * {@link org.apache.pdfbox.pdmodel.PDDocumentCatalog#setPageLabels(PDPageLabels)}.
      * </p>
      * 
      * @param document
      *            The document the page label dictionary is created for.
      * @param dict
      *            an existing page label dictionary
-     * @see PDDocumentCatalog#setPageLabels(PDPageLabels)
+     * @see org.apache.pdfbox.pdmodel.PDDocumentCatalog#setPageLabels(PDPageLabels)
      * @throws IOException
      *             If something goes wrong during the number tree conversion.
      */

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/common/function/PDFunction.java

@@ -316,7 +316,7 @@ private COSArray getDomainValues()
     /**
      * Clip the given input values to the ranges.
      * 
-     * @param inputArray the input values
+     * @param inputValues the input values
      * @return the clipped values
      */
     protected float[] clipToRange(float[] inputValues) 

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/common/function/PDFunctionType2.java

@@ -45,7 +45,7 @@ public class PDFunctionType2 extends PDFunction
     /**
      * Constructor.
      *
-     * @param functionStream The function .
+     * @param function The function .
      */
     public PDFunctionType2(COSBase function)
     {

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/documentinterchange/logicalstructure/PDMarkedContentReference.java

@@ -52,8 +52,7 @@ public PDMarkedContentReference()
     /**
      * Constructor for an existing marked content reference.
      * 
-     * @param pageDic the page dictionary
-     * @param mcid the marked content indentifier
+     * @param dictionary the page dictionary
      */
     public PDMarkedContentReference(COSDictionary dictionary)
     {

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/documentinterchange/logicalstructure/PDUserProperty.java

@@ -35,7 +35,7 @@ public class PDUserProperty extends PDDictionaryWrapper
     /**
      * Creates a new user property.
      * 
-     * @param the user attribute object
+     * @param userAttributeObject the user attribute object
      */
     public PDUserProperty(PDUserAttributeObject userAttributeObject)
     {
@@ -46,7 +46,7 @@ public PDUserProperty(PDUserAttributeObject userAttributeObject)
      * Creates a user property with a given dictionary.
      * 
      * @param dictionary the dictionary
-     * @param the user attribute object
+     * @param userAttributeObject the user attribute object
      */
     public PDUserProperty(COSDictionary dictionary,
         PDUserAttributeObject userAttributeObject)

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/documentinterchange/taggedpdf/PDExportFormatAttributeObject.java

@@ -79,7 +79,7 @@ public PDExportFormatAttributeObject(COSDictionary dictionary)
 
     /**
      * Gets the list numbering (ListNumbering). The default value is
-     * {@link #LIST_NUMBERING_NONE}.
+     * {@link PDListAttributeObject#LIST_NUMBERING_NONE}.
      * 
      * @return the list numbering
      */
@@ -93,15 +93,15 @@ public String getListNumbering()
      * Sets the list numbering (ListNumbering). The value shall be one of the
      * following:
      * <ul>
-     *   <li>{@link #LIST_NUMBERING_NONE},</li>
-     *   <li>{@link #LIST_NUMBERING_DISC},</li>
-     *   <li>{@link #LIST_NUMBERING_CIRCLE},</li>
-     *   <li>{@link #LIST_NUMBERING_SQUARE},</li>
-     *   <li>{@link #LIST_NUMBERING_DECIMAL},</li>
-     *   <li>{@link #LIST_NUMBERING_UPPER_ROMAN},</li>
-     *   <li>{@link #LIST_NUMBERING_LOWER_ROMAN},</li>
-     *   <li>{@link #LIST_NUMBERING_UPPER_ALPHA},</li>
-     *   <li>{@link #LIST_NUMBERING_LOWER_ALPHA}.</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_NONE},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_DISC},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_CIRCLE},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_SQUARE},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_DECIMAL},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_UPPER_ROMAN},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_LOWER_ROMAN},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_UPPER_ALPHA},</li>
+     *   <li>{@link PDListAttributeObject#LIST_NUMBERING_LOWER_ALPHA}.</li>
      * </ul>
      * 
      * @param listNumbering the list numbering
@@ -199,9 +199,9 @@ public String getScope()
      * contains it, or both the row and the column that contain it. The value
      * shall be one of the following:
      * <ul>
-     *   <li>{@link #SCOPE_ROW},</li>
-     *   <li>{@link #SCOPE_COLUMN}, or</li>
-     *   <li>{@link #SCOPE_BOTH}.</li>
+     *   <li>{@link PDTableAttributeObject#SCOPE_ROW},</li>
+     *   <li>{@link PDTableAttributeObject#SCOPE_COLUMN}, or</li>
+     *   <li>{@link PDTableAttributeObject#SCOPE_BOTH}.</li>
      * </ul>
      * 
      * @param scope the scope

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/documentinterchange/taggedpdf/PDLayoutAttributeObject.java

@@ -1011,7 +1011,7 @@ public void setInlineAlign(String inlineAlign)
      * Gets the style of the border drawn on each edge of a table cell
      * (TBorderStyle).
      * 
-     * @return
+     * @return the border style.
      */
     public Object getTBorderStyle()
     {

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/PublicKeySecurityHandler.java

@@ -66,7 +66,7 @@
  * This class implements the public key security handler
  * described in the PDF specification.
  *
- * @see PDF Spec 1.6 p104
+ * [PDF 1.6: p 104]
  *
  * @see PublicKeyProtectionPolicy to see how to protect document with this security handler.
  *
@@ -132,7 +132,7 @@ public void decryptDocument(PDDocument doc, DecryptionMaterial decryptionMateria
      * called from there. Only if decryption of single objects is needed this should be called instead.
      *
      * @param encDictionary  encryption dictionary, can be retrieved via {@link PDDocument#getEncryptionDictionary()}
-     * @param documentIDArray  document id which is returned via {@link COSDocument#getDocumentID()} (not used by this handler)
+     * @param documentIDArray  document id which is returned via {@link org.apache.pdfbox.cos.COSDocument#getDocumentID()} (not used by this handler)
      * @param decryptionMaterial Information used to decrypt the document.
      *
      * @throws IOException If there is an error accessing data.

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/encryption/SecurityHandler.java

@@ -501,7 +501,6 @@ private void decryptArray(COSArray array, long objNum, long genNum) throws Crypt
     /**
      * Getter of the property <tt>keyLength</tt>.
      * @return  Returns the keyLength.
-     * @uml.property  name="keyLength"
      */
     public int getKeyLength()
     {
@@ -542,7 +541,7 @@ public boolean isAES()
     /**
      * Set to true if AES for encryption and decryption should be used.
      * 
-     * @param aes if true AES will be used 
+     * @param aesValue if true AES will be used 
      * 
      */
     public void setAES(boolean aesValue)

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/font/PDFontDescriptor.java

@@ -524,7 +524,7 @@ private void setFlagBit( int bit, boolean value )
     /**
      * This will set the missing width for the font.
      *
-     * @param charSet The new missing width for the font.
+     * @param missingWidth The new missing width for the font.
      */
     public abstract void setMissingWidth( float missingWidth );
 

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/graphics/pattern/PDPatternResources.java

@@ -185,7 +185,7 @@ public static PDPatternResources create(COSDictionary resourceDictionary) throws
     /**
      * This will return the paint of the pattern.
      * 
-     * @param the height of the current page
+     * @param pageHeight the height of the current page
      * 
      * @return the paint of the pattern
      */

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/graphics/shading/AxialShadingPaint.java

@@ -45,7 +45,7 @@ public class AxialShadingPaint implements Paint
      * 
      * @param shadingType2 the shading resources
      * @param ctm current transformation matrix
-     * @param pageSizeValue size of the current page
+     * @param pageHeightValue size of the current page
      */
     public AxialShadingPaint(PDShadingType2 shadingType2, Matrix ctm, int pageHeightValue) 
     {

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/graphics/shading/PDShadingType1.java

@@ -182,7 +182,7 @@ private PDFunction[] getFunctionsArray() throws IOException
     /**
      * Convert the input value using the functions of the shading dictionary.
      * 
-     * @param inputValue the input value
+     * @param input the input values
      * @return the output values
      * @throws IOException thrown if something went wrong
      */

pdfbox/src/main/java/org/apache/pdfbox/pdmodel/graphics/shading/RadialShadingPaint.java

@@ -45,7 +45,7 @@ public class RadialShadingPaint implements Paint
      * 
      * @param shadingType3 the shading resources
      * @param ctm current transformation matrix
-     * @param pageSizeValue size of the current page
+     * @param pageHeightValue size of the current page
      */
     public RadialShadingPaint(PDShadingType3 shadingType3, Matrix ctm, int pageHeightValue) 
     {