Improve several kernel/pdf javadocs

DEVSIX-4123

Author: LodrKumquat

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

@@ -1391,8 +1391,9 @@ public void setFlushUnusedObjects(boolean flushUnusedObjects) {
     /**
      * This method returns a complete outline tree of the whole document.
      *
-     * @param updateOutlines if the flag is true, the method read the whole document and creates outline tree.
-     *                       If false the method gets cached outline tree (if it was cached via calling getOutlines method before).
+     * @param updateOutlines if the flag is {@code true}, the method reads the whole document and creates outline tree.
+     *                       If the flag is {@code false}, the method gets cached outline tree
+     *                       (if it was cached via calling getOutlines method before).
      * @return fully initialize {@link PdfOutline} object.
      */
     public PdfOutline getOutlines(boolean updateOutlines) {

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

@@ -436,6 +436,7 @@ public PdfPage copyTo(PdfDocument toDocument, IPdfPageExtraCopier copier) {
      *
      * @param toDocument a document to copy to.
      * @return copied {@link PdfFormXObject} object.
+     * @throws IOException if an I/O error occurs.
      */
     public PdfFormXObject copyAsFormXObject(PdfDocument toDocument) throws IOException {
         PdfFormXObject xObject = new PdfFormXObject(getCropBox());
@@ -955,6 +956,9 @@ public int getAnnotsSize() {
     /**
      * This method gets outlines of a current page
      *
+     * @param updateOutlines if the flag is {@code true}, the method reads the whole document and creates outline tree.
+     *                       If the flag is {@code false}, the method gets cached outline tree
+     *                       (if it was cached via calling getOutlines method before).
      * @return return all outlines of a current page
      */
     public List<PdfOutline> getOutlines(boolean updateOutlines) {
@@ -976,6 +980,7 @@ public boolean isIgnorePageRotationForContent() {
      * Default value - {@code false}.
      *
      * @param ignorePageRotationForContent - true to ignore rotation of the new content on the rotated page.
+     * @return this {@link PdfPage} instance.
      */
     public PdfPage setIgnorePageRotationForContent(boolean ignorePageRotationForContent) {
         this.ignorePageRotationForContent = ignorePageRotationForContent;

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

@@ -117,6 +117,7 @@ public class PdfReader implements Closeable, Serializable {
      *
      * @param byteSource source of bytes for the reader
      * @param properties properties of the created reader
+     * @throws IOException if an I/O error occurs
      */
     public PdfReader(IRandomAccessSource byteSource, ReaderProperties properties) throws IOException {
         this.properties = properties;
@@ -197,6 +198,10 @@ public void close() throws IOException {
     /**
      * The iText is not responsible if you decide to change the
      * value of this parameter.
+     *
+     * @param unethicalReading true to enable unethicalReading, false to disable it.
+     *                         By default unethicalReading is disabled.
+     * @return this {@link PdfReader} instance.
      */
     public PdfReader setUnethicalReading(boolean unethicalReading) {
         this.unethicalReading = unethicalReading;
@@ -315,6 +320,7 @@ public long getLastXref() {
      * Reads, decrypt and optionally decode stream bytes.
      * Note, this method doesn't store actual bytes in any internal structures.
      *
+     * @param stream a {@link PdfStream} stream instance to be read and optionally decoded.
      * @param decode true if to get decoded stream bytes, false if to leave it originally encoded.
      * @return byte[] array.
      * @throws IOException on error.
@@ -332,6 +338,7 @@ public byte[] readStreamBytes(PdfStream stream, boolean decode) throws IOExcepti
      * Reads and decrypt stream bytes.
      * Note, this method doesn't store actual bytes in any internal structures.
      *
+     * @param stream a {@link PdfStream} stream instance to be read
      * @return byte[] array.
      * @throws IOException on error.
      */
@@ -383,9 +390,10 @@ public byte[] readStreamBytesRaw(PdfStream stream) throws IOException {
     }
 
     /**
-     * Reads, decrypt and optionally decode stream bytes into {@link ByteArrayInputStream}.
+     * Reads, decrypts and optionally decodes stream bytes into {@link ByteArrayInputStream}.
      * User is responsible for closing returned stream.
      *
+     * @param stream a {@link PdfStream} stream instance to be read
      * @param decode true if to get decoded stream, false if to leave it originally encoded.
      * @return InputStream or {@code null} if reading was failed.
      * @throws IOException on error.
@@ -561,6 +569,7 @@ public long getPermissions() {
     /**
      * Gets encryption algorithm and access permissions.
      *
+     * @return {@code int} value corresponding to a certain type of encryption.
      * @see EncryptionConstants
      * @throws PdfException if the method has been invoked before the PDF document was read.
      */
@@ -653,6 +662,9 @@ public byte[] getModifiedFileId() {
     }
 
     /**
+     * Checks if the {@link PdfDocument} read with this {@link PdfReader} is encrypted.
+     *
+     * @return {@code true} is the document is encrypted, otherwise {@code false}.
      * @throws PdfException if the method has been invoked before the PDF document was read.
      */
     public boolean isEncrypted() {
@@ -665,6 +677,8 @@ public boolean isEncrypted() {
 
     /**
      * Parses the entire PDF
+     *
+     * @throws IOException if an I/O error occurs.
      */
     protected void readPdf() throws IOException {
         String version = tokens.checkPdfHeader();

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

@@ -108,8 +108,10 @@ public PdfResources() {
     }
 
     /**
-     * Adds font to resources and register PdfFont in the document for further flushing.
+     * Adds font to resources and registers PdfFont in the document for further flushing.
      *
+     * @param pdfDocument a {@link PdfDocument} instance to which the font is added for further flushing
+     * @param font a {@link PdfFont} instance to be added
      * @return added font resource name.
      */
     public PdfName addFont(PdfDocument pdfDocument, PdfFont font) {
@@ -311,6 +313,12 @@ protected boolean isModified() {
     }
 
     /**
+     * Sets the 'modified' flag to this {@link PdfResources} indirect object.
+     * The flag denotes that the object was modified since the document opening.
+     *
+     * @param isModified {@code true} if this {@link PdfResources} indirect object has been modified,
+     *                              otherwise {@code false}.
+     * @see PdfObject#setModified()
      * @deprecated Please use {@link #setModified()}.
      */
     @Deprecated