Improve several kernel JavaDocs

DEVSIX-4121

Author: introfog

kernel/src/main/java/com/itextpdf/kernel/numbering/RomanNumbering.java

@@ -66,7 +66,8 @@ public class RomanNumbering {
     /**
      * Returns a lower case roman representation of an integer.
      *
-     * @param number a number to be converted to roman notation.
+     * @param number a number to be converted to roman notation
+     * @return a lower case roman representation of an integer
      */
     public static String toRomanLowerCase(int number) {
         return convert(number);
@@ -75,7 +76,8 @@ public static String toRomanLowerCase(int number) {
     /**
      * Returns an upper case roman representation of an integer.
      *
-     * @param number a number to be converted to roman notation.
+     * @param number a number to be converted to roman notation
+     * @return an upper case roman representation of an integer
      */
     public static String toRomanUpperCase(int number) {
         return convert(number).toUpperCase();
@@ -84,9 +86,10 @@ public static String toRomanUpperCase(int number) {
     /**
      * Returns a roman representation of an integer.
      *
-     * @param number     a number to be converted to roman notation.
+     * @param number     a number to be converted to roman notation
      * @param upperCase <code>true</code> for upper case representation,
-     *                  <code>false</code> for lower case one.
+     *                  <code>false</code> for lower case one
+     * @return a roman representation of an integer
      */
     public static String toRoman(int number, boolean upperCase) {
         return upperCase ? toRomanUpperCase(number) : toRomanLowerCase(number);

kernel/src/main/java/com/itextpdf/kernel/pdf/PdfPage.java

@@ -1194,8 +1194,8 @@ public void addAssociatedFile(PdfFileSpec fs) {
     /**
      * Returns files associated with PDF page.
      *
-     * @param create iText will create AF array if it doesn't exist and create value is true
-     * @return associated files array.
+     * @param create defines whether AF arrays will be created if it doesn't exist
+     * @return associated files array
      */
     public PdfArray getAssociatedFiles(boolean create) {
         PdfArray afArray = getPdfObject().getAsArray(PdfName.AF);

kernel/src/main/java/com/itextpdf/kernel/pdf/annot/PdfAnnotation.java

@@ -1094,8 +1094,8 @@ public void addAssociatedFile(PdfFileSpec fs) {
     /**
      * Returns files associated with PDF annotation.
      *
-     * @param create iText will create AF array if it doesn't exist and create value is true
-     * @return associated files array.
+     * @param create defines whether AF arrays will be created if it doesn't exist
+     * @return associated files array
      */
     public PdfArray getAssociatedFiles(boolean create) {
         PdfArray afArray = getPdfObject().getAsArray(PdfName.AF);

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/CanvasGraphicsState.java

@@ -164,6 +164,14 @@ public Matrix getCtm() {
 
     /**
      * Updates current transformation matrix.
+     * The third column will always be [0 0 1]
+     *
+     * @param a element at (1,1) of the transformation matrix
+     * @param b element at (1,2) of the transformation matrix
+     * @param c element at (2,1) of the transformation matrix
+     * @param d element at (2,2) of the transformation matrix
+     * @param e element at (3,1) of the transformation matrix
+     * @param f element at (3,2) of the transformation matrix
      */
     public void updateCtm(float a, float b, float c, float d, float e, float f) {
         updateCtm(new Matrix(a, b, c, d, e, f));

kernel/src/main/java/com/itextpdf/kernel/pdf/tagging/PdfStructElem.java

@@ -475,8 +475,8 @@ public void addAssociatedFile(PdfFileSpec fs) {
     /**
      * Returns files associated with structure element.
      *
-     * @param create iText will create AF array if it doesn't exist and create value is true
-     * @return associated files array.
+     * @param create defines whether AF arrays will be created if it doesn't exist
+     * @return associated files array
      */
     public PdfArray getAssociatedFiles(boolean create) {
         PdfArray afArray = getPdfObject().getAsArray(PdfName.AF);

kernel/src/main/java/com/itextpdf/kernel/pdf/tagging/PdfStructTreeRoot.java

@@ -440,8 +440,8 @@ public void addAssociatedFile(PdfFileSpec fs) {
     /**
      * Returns files associated with structure tree root.
      *
-     * @param create iText will create AF array if it doesn't exist and create value is true
-     * @return associated files array.
+     * @param create defines whether AF arrays will be created if it doesn't exist
+     * @return associated files array
      */
     public PdfArray getAssociatedFiles(boolean create) {
         PdfArray afArray = getPdfObject().getAsArray(PdfName.AF);

kernel/src/main/java/com/itextpdf/kernel/pdf/tagutils/TagStructureContext.java

@@ -316,8 +316,10 @@ public IRoleMappingResolver resolveMappingToStandardOrDomainSpecificRole(String
     /**
      * Removes annotation content item from the tag structure.
      * If annotation is not added to the document or is not tagged, nothing will happen.
+     *
+     * @param annotation the {@link PdfAnnotation} that will be removed from the tag structure
      * @return {@link TagTreePointer} instance which points at annotation tag parent if annotation was removed,
-     * otherwise returns null.
+     * otherwise returns null
      */
     public TagTreePointer removeAnnotationTag(PdfAnnotation annotation) {
         PdfStructElem structElem = null;
@@ -365,8 +367,9 @@ public TagTreePointer removeContentItem(PdfPage page, int mcid) {
     /**
      * Removes all tags that belong only to this page. The logic which defines if tag belongs to the page is described
      * at {@link #flushPageTags(PdfPage)}.
+     *
      * @param page page that defines which tags are to be removed
-     * @return current {@link TagStructureContext} instance.
+     * @return current {@link TagStructureContext} instance
      */
     public TagStructureContext removePageTags(PdfPage page) {
         PdfStructTreeRoot structTreeRoot = document.getStructTreeRoot();
@@ -392,7 +395,9 @@ public TagStructureContext removePageTags(PdfPage page) {
      * <br><br>
      * If some of the page's tags have waiting state (see {@link WaitingTagsManager} these tags are considered
      * as not yet finished ones, and they and their children won't be flushed.
-     * @param page a page which tags will be flushed.
+     *
+     * @param page a page which tags will be flushed
+     * @return current {@link TagStructureContext} instance
      */
     public TagStructureContext flushPageTags(PdfPage page) {
         PdfStructTreeRoot structTreeRoot = document.getStructTreeRoot();

kernel/src/main/java/com/itextpdf/kernel/pdf/tagutils/TagTreePointer.java

@@ -168,7 +168,8 @@ public PdfPage getCurrentPage() {
      * NOTE: It's important to set a {@code null} for this value, when tagging of this stream content is finished.
      *
      * @param contentStream the content stream which content will be tagged with this instance of {@code TagTreePointer}
-     *                      or {@code null} if content stream tagging is finished.
+     *                      or {@code null} if content stream tagging is finished
+     * @return current {@link TagTreePointer} instance
      */
     public TagTreePointer setContentStreamForTagging(PdfStream contentStream) {
         this.contentStream = contentStream;

kernel/src/main/java/com/itextpdf/kernel/pdf/xobject/PdfTransparencyGroup.java

@@ -61,7 +61,8 @@ public PdfTransparencyGroup() {
 
     /**
      * Determining the initial backdrop against which its stack is composited.
-     * @param isolated
+     *
+     * @param isolated defines whether the {@link PdfName#I} flag will be set or removed
      */
     public void setIsolated(boolean isolated) {
         if (isolated) {
@@ -73,7 +74,8 @@ public void setIsolated(boolean isolated) {
 
     /**
      * Determining whether the objects within the stack are composited with one another or only with the group's backdrop.
-     * @param knockout
+     *
+     * @param knockout defines whether the {@link PdfName#K} flag will be set or removed
      */
     public void setKnockout(boolean knockout) {
         if (knockout) {

kernel/src/main/java/com/itextpdf/kernel/pdf/xobject/PdfXObject.java

@@ -138,9 +138,9 @@ public void addAssociatedFile(PdfFileSpec fs) {
     /**
      * Returns files associated with XObject.
      *
-     * @return associated files array.
+     * @param create defines whether AF arrays will be created if it doesn't exist
+     * @return associated files array
      */
-
     public PdfArray getAssociatedFiles(boolean create) {
         PdfArray afArray = getPdfObject().getAsArray(PdfName.AF);
         if (afArray == null && create) {