fix javadocs

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

10 files changed, 103 insertions, 138 deletions

diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/DeferredSXSSFSheet.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/DeferredSXSSFSheet.java
index edd1d04497..5687ef90de 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/DeferredSXSSFSheet.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/DeferredSXSSFSheet.java
@@ -25,7 +25,7 @@ import org.apache.poi.util.Beta;
 import org.apache.poi.xssf.usermodel.XSSFSheet;
 
 /**
- * A variant of SXSSFSheet that uses a <code>RowGeneratorFunction</code></code> to lazily create rows.
+ * A variant of SXSSFSheet that uses a {@code RowGeneratorFunction} to lazily create rows.
  *
  *  This variant is experimental and APIs may change at short notice.
  *
@@ -36,20 +36,20 @@ import org.apache.poi.xssf.usermodel.XSSFSheet;
 @Beta
 public class DeferredSXSSFSheet extends SXSSFSheet {
     private RowGeneratorFunction rowGenerator;
-    
+
     public DeferredSXSSFSheet(DeferredSXSSFWorkbook workbook, XSSFSheet xSheet) throws IOException {
         super(workbook, xSheet, workbook.getRandomAccessWindowSize());
     }
-    
+
     @Override
     public InputStream getWorksheetXMLInputStream() throws IOException {
         throw new RuntimeException("Not supported by DeferredSXSSFSheet");
     }
-    
+
     public void setRowGenerator(RowGeneratorFunction rowGenerator) {
         this.rowGenerator = rowGenerator;
     }
-    
+
     public void writeRows(OutputStream out) throws IOException {
         // delayed creation of SheetDataWriter
         _writer = ((DeferredSXSSFWorkbook) _workbook).createSheetDataWriter(out);
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java
index aa76fba89d..1e9047009e 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java
@@ -30,10 +30,10 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName;
  * Represents a defined named range in a SpreadsheetML workbook.
  * <p>
  * Defined names are descriptive text that is used to represents a cell, range of cells, formula, or constant value.
- * Use easy-to-understand names, such as Products, to refer to hard to understand ranges, such as <code>Sales!C20:C30</code>.
+ * Use easy-to-understand names, such as Products, to refer to hard to understand ranges, such as {@code Sales!C20:C30}.
  * </p>
  * Example:
- * <pre><blockquote>
+ * <pre>{@code
  *   XSSFWorkbook wb = new XSSFWorkbook();
  *   XSSFSheet sh = wb.createSheet("Sheet1");
  *
@@ -49,7 +49,7 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName;
  *   name2.setLocalSheetId(0);
  *   name2.setRefersToFormula("Sheet1!$B$3");
  *
- * </blockquote></pre>
+ * }</pre>
  */
 public final class XSSFName implements Name {
 
@@ -79,11 +79,13 @@ public final class XSSFName implements Name {
     public static final String BUILTIN_EXTRACT = "_xlnm.Extract:";
 
     /**
-     * ?an be one of the following
+     * Can be one of the following
+     * <ul>
      * <li> this defined name refers to a range to which an advanced filter has been
      * applied. This represents the source data range, unfiltered.
      * <li> This defined name refers to a range to which an AutoFilter has been
      * applied
+     * </ul>
      */
     public static final String BUILTIN_FILTER_DB = "_xlnm._FilterDatabase";
 
@@ -102,8 +104,8 @@ public final class XSSFName implements Name {
      */
     public static final String BUILTIN_SHEET_TITLE = "_xlnm.Sheet_Title";
 
-    private XSSFWorkbook _workbook;
-    private CTDefinedName _ctName;
+    private final XSSFWorkbook _workbook;
+    private final CTDefinedName _ctName;
 
     /**
      * Creates an XSSFName object - called internally by XSSFWorkbook.
@@ -129,6 +131,7 @@ public final class XSSFName implements Name {
      *
      * @return text name of this defined name
      */
+    @Override
     public String getNameName() {
         return _ctName.getName();
     }
@@ -140,7 +143,7 @@ public final class XSSFName implements Name {
      * <p>
      * A name must always be unique within its scope. POI prevents you from defining a name that is not unique
      * within its scope. However you can use the same name in different scopes. Example:
-     * <pre><blockquote>
+     * <pre>{@code
      * //by default names are workbook-global
      * XSSFName name;
      * name = workbook.createName();
@@ -158,11 +161,12 @@ public final class XSSFName implements Name {
      * name.setSheetIndex(0);
      * name.setNameName("sales_08");  //will throw an exception: "The sheet already contains this name (case-insensitive)"
      *
-     * </blockquote></pre>
-    * </p>
+     * }</pre>
+     *
      * @param name name of this defined name
      * @throws IllegalArgumentException if the name is invalid or the workbook already contains this name (case-insensitive)
      */
+    @Override
     public void setNameName(String name) {
         validateName(name);
 
@@ -180,6 +184,7 @@ public final class XSSFName implements Name {
         _workbook.updateName(this, oldName);
     }
 
+    @Override
     public String getRefersToFormula() {
         String result = _ctName.getStringValue();
         if (result == null || result.length() < 1) {
@@ -188,6 +193,7 @@ public final class XSSFName implements Name {
         return result;
     }
 
+    @Override
     public void setRefersToFormula(String formulaText) {
         XSSFEvaluationWorkbook fpb = XSSFEvaluationWorkbook.create(_workbook);
         //validate through the FormulaParser
@@ -196,6 +202,7 @@ public final class XSSFName implements Name {
         _ctName.setStringValue(formulaText);
     }
 
+    @Override
     public boolean isDeleted(){
         String formulaText = getRefersToFormula();
         if (formulaText == null) {
@@ -211,6 +218,7 @@ public final class XSSFName implements Name {
      *
      * @param index the sheet index this name applies to, -1 unsets this property making the name workbook-global
      */
+    @Override
     public void setSheetIndex(int index) {
         int lastSheetIx = _workbook.getNumberOfSheets() - 1;
         if (index < -1 || index > lastSheetIx) {
@@ -230,6 +238,7 @@ public final class XSSFName implements Name {
      *
      * @return the sheet index this name applies to, -1 if this name applies to the entire workbook
      */
+    @Override
     public int getSheetIndex() {
         return _ctName.isSetLocalSheetId() ? (int) _ctName.getLocalSheetId() : -1;
     }
@@ -238,8 +247,9 @@ public final class XSSFName implements Name {
      * Indicates that the defined name refers to a user-defined function.
      * This attribute is used when there is an add-in or other code project associated with the file.
      *
-     * @param value <code>true</code> indicates the name refers to a function.
+     * @param value {@code true} indicates the name refers to a function.
      */
+    @Override
     public void setFunction(boolean value) {
         _ctName.setFunction(value);
     }
@@ -248,7 +258,7 @@ public final class XSSFName implements Name {
      * Indicates that the defined name refers to a user-defined function.
      * This attribute is used when there is an add-in or other code project associated with the file.
      *
-     * @return <code>true</code> indicates the name refers to a function.
+     * @return {@code true} indicates the name refers to a function.
      */
     public boolean getFunction() {
         return _ctName.getFunction();
@@ -282,6 +292,7 @@ public final class XSSFName implements Name {
      * @return sheet name, which this named range referred to.
      * Empty string if the referenced sheet name was not found.
      */
+    @Override
     public String getSheetName() {
         if (_ctName.isSetLocalSheetId()) {
             // Given as explicit sheet id
@@ -296,8 +307,9 @@ public final class XSSFName implements Name {
     /**
      * Is the name refers to a user-defined function ?
      *
-     * @return <code>true</code> if this name refers to a user-defined function
+     * @return {@code true} if this name refers to a user-defined function
      */
+    @Override
     public boolean isFunctionName() {
         return getFunction();
     }
@@ -308,6 +320,7 @@ public final class XSSFName implements Name {
      *
      * @return true if this name is a hidden one
      */
+    @Override
     public boolean isHidden() {
         return _ctName.getHidden();
     }
@@ -317,6 +330,7 @@ public final class XSSFName implements Name {
      *
      * @return the user comment for this named range
      */
+    @Override
     public String getComment() {
         return _ctName.getComment();
     }
@@ -326,6 +340,7 @@ public final class XSSFName implements Name {
      *
      * @param comment  the user comment for this named range
      */
+    @Override
     public void setComment(String comment) {
         _ctName.setComment(comment);
     }
@@ -337,12 +352,12 @@ public final class XSSFName implements Name {
 
     /**
      * Compares this name to the specified object.
-     * The result is <code>true</code> if the argument is XSSFName and the
+     * The result is {@code true} if the argument is XSSFName and the
      * underlying CTDefinedName bean equals to the CTDefinedName representing this name
      *
-     * @param   o   the object to compare this <code>XSSFName</code> against.
-     * @return  <code>true</code> if the <code>XSSFName </code>are equal;
-     *          <code>false</code> otherwise.
+     * @param   o   the object to compare this {@code XSSFName} against.
+     * @return  {@code true} if the {@code XSSFName }are equal;
+     *          {@code false} otherwise.
      */
     @Override
     public boolean equals(Object o) {
@@ -372,8 +387,6 @@ public final class XSSFName implements Name {
      * Case sensitivity: all names are case-insensitive
      *
      * Uniqueness: must be unique (for names with the same scope)
-     *
-     * @param name
      */
     private static void validateName(String name) {
 
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java
index cfda49b0b0..0484773ecc 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java
@@ -102,12 +102,12 @@ public class XSSFRow implements Row, Comparable<XSSFRow> {
 
     /**
      * Cell iterator over the physically defined cells:
-     * <blockquote><pre>
+     * <pre>{@code
      * for (Iterator<Cell> it = row.cellIterator(); it.hasNext(); ) {
      *     Cell cell = it.next();
      *     ...
      * }
-     * </pre></blockquote>
+     * }</pre>
      *
      * @return an iterator over cells in this row.
      */
@@ -133,22 +133,22 @@ public class XSSFRow implements Row, Comparable<XSSFRow> {
     }
 
     /**
-     * Compares two <code>XSSFRow</code> objects.  Two rows are equal if they belong to the same worksheet and
+     * Compares two {@code XSSFRow} objects.  Two rows are equal if they belong to the same worksheet and
      * their row indexes are equal.
      *
-     * @param   other   the <code>XSSFRow</code> to be compared.
+     * @param   other   the {@code XSSFRow} to be compared.
      * @return  <ul>
      *      <li>
-     *      the value <code>0</code> if the row number of this <code>XSSFRow</code> is
-     *      equal to the row number of the argument <code>XSSFRow</code>
+     *      the value {@code 0} if the row number of this {@code XSSFRow} is
+     *      equal to the row number of the argument {@code XSSFRow}
      *      </li>
      *      <li>
-     *      a value less than <code>0</code> if the row number of this this <code>XSSFRow</code> is
-     *      numerically less than the row number of the argument <code>XSSFRow</code>
+     *      a value less than {@code 0} if the row number of this this {@code XSSFRow} is
+     *      numerically less than the row number of the argument {@code XSSFRow}
      *      </li>
      *      <li>
-     *      a value greater than <code>0</code> if the row number of this this <code>XSSFRow</code> is
-     *      numerically greater than the row number of the argument <code>XSSFRow</code>
+     *      a value greater than {@code 0} if the row number of this this {@code XSSFRow} is
+     *      numerically greater than the row number of the argument {@code XSSFRow}
      *      </li>
      *      </ul>
      * @throws IllegalArgumentException if the argument row belongs to a different worksheet
@@ -186,7 +186,7 @@ public class XSSFRow implements Row, Comparable<XSSFRow> {
      * Use this to create new cells within the row and return it.
      * <p>
      * The cell that is returned is a {@link CellType#BLANK}. The type can be changed
-     * either through calling <code>setCellValue</code> or <code>setCellType</code>.
+     * either through calling {@code setCellValue} or {@code setCellType}.
      * </p>
      * @param columnIndex - the column number this cell represents
      * @return Cell a high level representation of the created cell.
@@ -359,7 +359,7 @@ public class XSSFRow implements Row, Comparable<XSSFRow> {
     /**
      *  Set the height in "twips" or  1/20th of a point.
      *
-     * @param height the height in "twips" or  1/20th of a point. <code>-1</code>  resets to the default height
+     * @param height the height in "twips" or  1/20th of a point. {@code -1}  resets to the default height
      */
     @Override
     public void setHeight(short height) {
@@ -380,7 +380,7 @@ public class XSSFRow implements Row, Comparable<XSSFRow> {
     /**
      * Set the row's height in points.
      *
-     * @param height the height in points. <code>-1</code>  resets to the default height
+     * @param height the height in points. {@code -1}  resets to the default height
      */
     @Override
     public void setHeightInPoints(float height) {
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
index cf910a7cd8..45216a8cdd 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
@@ -813,22 +813,19 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su
     /**
      * Create a new sheet for this Workbook and return the high level representation.
      * Use this to create new sheets.
-     *
      * <p>
-     *     Note that Excel allows sheet names up to 31 chars in length but other applications
-     *     (such as OpenOffice) allow more. Some versions of Excel crash with names longer than 31 chars,
-     *     others - truncate such names to 31 character.
-     * </p>
+     * Note that Excel allows sheet names up to 31 chars in length but other applications
+     * (such as OpenOffice) allow more. Some versions of Excel crash with names longer than 31 chars,
+     * others - truncate such names to 31 character.
      * <p>
-     *     POI's SpreadsheetAPI silently truncates the input argument to 31 characters.
-     *     Example:
-     *
-     *     <pre>{@code
-     *     Sheet sheet = workbook.createSheet("My very long sheet name which is longer than 31 chars"); // will be truncated
-     *     assert 31 == sheet.getSheetName().length();
-     *     assert "My very long sheet name which i" == sheet.getSheetName();
-     *     }</pre>
-     * </p>
+     * POI's SpreadsheetAPI silently truncates the input argument to 31 characters.
+     * Example:
+     *
+     * <pre>{@code
+     * Sheet sheet = workbook.createSheet("My very long sheet name which is longer than 31 chars"); // will be truncated
+     * assert 31 == sheet.getSheetName().length();
+     * assert "My very long sheet name which i" == sheet.getSheetName();
+     * }</pre>
      *
      * Except the 31-character constraint, Excel applies some other rules:
      * <p>
@@ -845,12 +842,10 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su
      * <li> closing square bracket (]) </li>
      * </ul>
      * The string MUST NOT begin or end with the single quote (') character.
-     * </p>
-     *
      * <p>
      * See {@link WorkbookUtil#createSafeSheetName(String nameProposal)}
      *      for a safe way to create valid names
-     * </p>
+     *
      * @param sheetname  sheetname to set for the sheet.
      * @return Sheet representing the new sheet.
      * @throws IllegalArgumentException if the name is null or invalid
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/BreakClear.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/BreakClear.java
index 33ece8f2e7..332e9c2d82 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/BreakClear.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/BreakClear.java
@@ -50,9 +50,9 @@ public enum BreakClear {
      * </li>
      * <li> If this line is not broken into multiple regions, then treat this
      * break as a text wrapping break of type none. </li>
-     * </ul>
      * <li> If the parent paragraph is right to left, then these behaviors are
      * also reversed. </li>
+     * </ul>
      */
     LEFT(2),
 
@@ -81,7 +81,7 @@ public enum BreakClear {
      */
     ALL(4);
 
-    private static Map<Integer, BreakClear> imap = new HashMap<>();
+    private static final Map<Integer, BreakClear> imap = new HashMap<>();
 
     static {
         for (BreakClear p : values()) {
@@ -91,7 +91,7 @@ public enum BreakClear {
 
     private final int value;
 
-    private BreakClear(int val) {
+    BreakClear(int val) {
         value = val;
     }
 
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFEndnotes.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFEndnotes.java
index 1df57f6d56..1ac9a05d98 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFEndnotes.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFEndnotes.java
@@ -90,7 +90,6 @@ public class XWPFEndnotes extends XWPFAbstractFootnotesEndnotes {
     /**
      * Remove the specified footnote if present.
      *
-     * @param pos
      * @return True if the footnote was removed.
      * @since 4.0.0
      */
@@ -134,9 +133,6 @@ public class XWPFEndnotes extends XWPFAbstractFootnotesEndnotes {
 
     /**
      * add an {@link XWPFEndnote} to the document
-     *
-     * @param endnote
-     * @throws IOException
      */
     public void addEndnote(XWPFEndnote endnote) {
         listFootnote.add(endnote);
@@ -148,7 +144,6 @@ public class XWPFEndnotes extends XWPFAbstractFootnotesEndnotes {
      *
      * @param note Note to add
      * @return New {@link XWPFEndnote}
-     * @throws IOException
      */
     @Internal
     public XWPFEndnote addEndnote(CTFtnEdn note) {
@@ -164,6 +159,7 @@ public class XWPFEndnotes extends XWPFAbstractFootnotesEndnotes {
      * @param id End note ID.
      * @return The end note or null if not found.
      */
+    @Override
     public XWPFEndnote getFootnoteById(int id) {
         return (XWPFEndnote)super.getFootnoteById(id);
     }
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFFootnotes.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFFootnotes.java
index 8f7c591c5a..278e16da1a 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFFootnotes.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFFootnotes.java
@@ -136,7 +136,6 @@ public class XWPFFootnotes extends XWPFAbstractFootnotesEndnotes {
      * Add an {@link XWPFFootnote} to the document
      *
      * @param footnote Footnote to add
-     * @throws IOException
      */
     public void addFootnote(XWPFFootnote footnote) {
         listFootnote.add(footnote);
@@ -147,7 +146,6 @@ public class XWPFFootnotes extends XWPFAbstractFootnotesEndnotes {
      * Add a CT footnote to the document
      *
      * @param note CTFtnEdn to add.
-     * @throws IOException
      */
     @Internal
     public XWPFFootnote addFootnote(CTFtnEdn note) {
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java
index 4f09eb64de..ac3b8200e0 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java
@@ -93,6 +93,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
         return headerFooter;
     }
 
+    @Override
     public List<IBodyElement> getBodyElements() {
         return Collections.unmodifiableList(bodyElements);
     }
@@ -104,6 +105,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
      * there could be more in certain cases, or
      * a table.
      */
+    @Override
     public List<XWPFParagraph> getParagraphs() {
         return Collections.unmodifiableList(paragraphs);
     }
@@ -117,6 +119,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
      * complex headers/footers have a table or two
      * in addition.
      */
+    @Override
     public List<XWPFTable> getTables() throws ArrayIndexOutOfBoundsException {
         return Collections.unmodifiableList(tables);
     }
@@ -129,9 +132,9 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
     public String getText() {
         StringBuilder t = new StringBuilder(64);
         //TODO: simplify this to get ibody elements in order
-        for (int i = 0; i < paragraphs.size(); i++) {
-            if (!paragraphs.get(i).isEmpty()) {
-                String text = paragraphs.get(i).getText();
+        for (XWPFParagraph paragraph : paragraphs) {
+            if (!paragraph.isEmpty()) {
+                String text = paragraph.getText();
                 if (text != null && text.length() > 0) {
                     t.append(text);
                     t.append('\n');
@@ -139,8 +142,8 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
             }
         }
 
-        for (int i = 0; i < tables.size(); i++) {
-            String text = tables.get(i).getText();
+        for (XWPFTable table : tables) {
+            String text = table.getText();
             if (text != null && text.length() > 0) {
                 t.append(text);
                 t.append('\n');
@@ -149,7 +152,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
 
         for (IBodyElement bodyElement : getBodyElements()) {
             if (bodyElement instanceof XWPFSDT) {
-                t.append(((XWPFSDT) bodyElement).getContent().getText() + '\n');
+                t.append(((XWPFSDT) bodyElement).getContent().getText()).append('\n');
             }
         }
         return t.toString();
@@ -167,9 +170,8 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
      * if there is a corresponding {@link XWPFTable} of the parameter ctTable in the tableList of this header
      * the method will return this table
      * if there is no corresponding {@link XWPFTable} the method will return null
-     *
-     * @param ctTable
      */
+    @Override
     public XWPFTable getTable(CTTbl ctTable) {
         for (XWPFTable table : tables) {
             if (table == null)
@@ -193,6 +195,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
      * Returns the paragraph that holds
      * the text of the header or footer.
      */
+    @Override
     public XWPFParagraph getParagraphArray(int pos) {
         if(pos >= 0 && pos<paragraphs.size()){
             return paragraphs.get(pos);
@@ -283,9 +286,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
     /**
      * returns the PictureData by blipID
      *
-     * @param blipID
      * @return XWPFPictureData of a specificID
-     * @throws Exception
      */
     public XWPFPictureData getPictureDataByID(String blipID) {
         POIXMLDocumentPart relatedPart = getRelationById(blipID);
@@ -368,9 +369,9 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
     /**
      * add a new paragraph at position of the cursor
      *
-     * @param cursor
      * @return the inserted paragraph
      */
+    @Override
     public XWPFParagraph insertNewParagraph(XmlCursor cursor) {
         if (isCursorInHdrF(cursor)) {
             String uri = CTP.type.getName().getNamespaceURI();
@@ -410,9 +411,9 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
 
 
     /**
-     * @param cursor
      * @return the inserted table
      */
+    @Override
     public XWPFTable insertNewTbl(final XmlCursor cursor) {
         if (isCursorInHdrF(cursor)) {
             String uri = CTTbl.type.getName().getNamespaceURI();
@@ -453,8 +454,6 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
 
     /**
      * verifies that cursor is on the right position
-     *
-     * @param cursor
      */
     private boolean isCursorInHdrF(XmlCursor cursor) {
         XmlCursor verify = cursor.newCursor();
@@ -471,9 +470,8 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
 
     /**
      * Returns the table at position pos
-     *
-     * @see org.apache.poi.xwpf.usermodel.IBody#getTableArray(int)
      */
+    @Override
     public XWPFTable getTableArray(int pos) {
         if (pos >= 0 && pos < tables.size()) {
             return tables.get(pos);
@@ -483,10 +481,8 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
 
     /**
      * inserts an existing XWPFTable to the arrays bodyElements and tables
-     *
-     * @param pos
-     * @param table
      */
+    @Override
     public void insertTable(int pos, XWPFTable table) {
         bodyElements.add(pos, table);
         int i = 0;
@@ -526,9 +522,8 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
 
     /**
      * get the TableCell which belongs to the TableCell
-     *
-     * @param cell
      */
+    @Override
     public XWPFTableCell getTableCell(CTTc cell) {
         XmlCursor cursor = cell.newCursor();
         cursor.toParent();
@@ -553,6 +548,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
         return tableRow.getTableCell(cell);
     }
 
+    @Override
     public XWPFDocument getXWPFDocument() {
         if (document != null) {
             return document;
@@ -567,9 +563,8 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo
 
     /**
      * returns the Part, to which the body belongs, which you need for adding relationship to other parts
-     *
-     * @see org.apache.poi.xwpf.usermodel.IBody#getPart()
      */
+    @Override
     public POIXMLDocumentPart getPart() {
         return this;
     }
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java
index bbf59867d1..c2228ce143 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java
@@ -33,11 +33,11 @@ import org.openxmlformats.schemas.officeDocument.x2006.sharedTypes.STOnOff1;
 import org.openxmlformats.schemas.wordprocessingml.x2006.main.*;
 
 /**
- * <p>A Paragraph within a Document, Table, Header etc.</p>
- * <p>
- * <p>A paragraph has a lot of styling information, but the
+ * A Paragraph within a Document, Table, Header etc.<p>
+ *
+ * A paragraph has a lot of styling information, but the
  * actual text (possibly along with more styling) is held on
- * the child {@link XWPFRun}s.</p>
+ * the child {@link XWPFRun}s.
  */
 public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Paragraph {
     private final CTP paragraph;
@@ -49,7 +49,7 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
     protected List<XWPFRun> runs;
     protected List<IRunElement> iruns;
 
-    private StringBuilder footnoteText = new StringBuilder(64);
+    private final StringBuilder footnoteText = new StringBuilder(64);
 
     public XWPFParagraph(CTP prgrph, IBody part) {
         this.paragraph = prgrph;
@@ -176,8 +176,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
 
     /**
      * Return literal runs and sdt/content control objects.
-     *
-     * @return List<IRunElement>
      */
     public List<IRunElement> getIRuns() {
         return Collections.unmodifiableList(iruns);
@@ -252,8 +250,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
 
     /**
      * setNumID of Paragraph
-     *
-     * @param numPos
      */
     public void setNumID(BigInteger numPos) {
         if (paragraph.getPPr() == null) {
@@ -271,7 +267,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
     /**
      * setNumILvl of Paragraph
      *
-     * @param iLvl
      * @since 4.1.2
      */
     public void setNumILvl(BigInteger iLvl) {
@@ -484,13 +479,11 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
      * Returns the paragraph alignment which shall be applied to text in this
      * paragraph.
      * <p>
-     * <p>
      * If this element is not set on a given paragraph, its value is determined
      * by the setting previously set at any level of the style hierarchy (i.e.
      * that previous setting remains unchanged). If this setting is never
      * specified in the style hierarchy, then no alignment is applied to the
      * paragraph.
-     * </p>
      *
      * @return the paragraph alignment of this paragraph.
      */
@@ -504,13 +497,11 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
      * Specifies the paragraph alignment which shall be applied to text in this
      * paragraph.
      * <p>
-     * <p>
      * If this element is not set on a given paragraph, its value is determined
      * by the setting previously set at any level of the style hierarchy (i.e.
      * that previous setting remains unchanged). If this setting is never
      * specified in the style hierarchy, then no alignment is applied to the
      * paragraph.
-     * </p>
      *
      * @param align the paragraph alignment to apply to this paragraph.
      */
@@ -610,7 +601,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
      * Specifies the border which shall be displayed above a set of paragraphs
      * which have the same set of paragraph border settings.
      * <p>
-     * <p>
      * To determine if any two adjoining paragraphs shall have an individual top
      * and bottom border or a between border, the set of borders on the two
      * adjoining paragraphs are compared. If the border information on those two
@@ -620,14 +610,13 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
      * respectively. If this border specifies a space attribute, that value
      * determines the space above the text (ignoring any spacing above) which
      * should be left before this border is drawn, specified in points.
-     * </p>
      * <p>
      * If this element is omitted on a given paragraph, its value is determined
      * by the setting previously set at any level of the style hierarchy (i.e.
      * that previous setting remains unchanged). If this setting is never
      * specified in the style hierarchy, then no between border shall be applied
      * above identical paragraphs.
-     * </p>
+     * <p>
      * <b>This border can only be a line border.</b>
      *
      * @param border one of the defined Border styles, see {@link Borders}
@@ -1466,8 +1455,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
     /**
      * add a new run at the end of the position of
      * the content of parameter run
-     *
-     * @param run
      */
     protected void addRun(CTR run) {
         int pos;
@@ -1643,9 +1630,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
 
     /**
      * verifies that cursor is on the right position
-     *
-     * @param cursor
-     * @return
      */
     private boolean isCursorInParagraph(XmlCursor cursor) {
         XmlCursor verify = cursor.newCursor();
@@ -1659,9 +1643,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
      * this methods parse the paragraph and search for the string searched.
      * If it finds the string, it will return true and the position of the String
      * will be saved in the parameter startPos.
-     *
-     * @param searched
-     * @param startPos
      */
     public TextSegment searchText(String searched, PositionInParagraph startPos) {
         int startRun = startPos.getRun(),
@@ -1731,8 +1712,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
 
     /**
      * get a Text
-     *
-     * @param segment
      */
     public String getText(TextSegment segment) {
         int runBegin = segment.getBeginRun();
@@ -1770,7 +1749,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
     /**
      * removes a Run at the position pos in the paragraph
      *
-     * @param pos
      * @return true if the run was removed
      */
     public boolean removeRun(int pos) {
@@ -1810,9 +1788,7 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
     /**
      * Is there only one ctHyperlink in all runs
      *
-     * @param run
-     *            hyperlink run
-     * @return
+     * @param run hyperlink run
      */
     private boolean isTheOnlyCTHyperlinkInRuns(XWPFHyperlinkRun run) {
         CTHyperlink ctHyperlink = run.getCTHyperlink();
@@ -1825,9 +1801,7 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
     /**
      * Is there only one ctField in all runs
      *
-     * @param run
-     *            field run
-     * @return
+     * @param run field run
      */
     private boolean isTheOnlyCTFieldInRuns(XWPFFieldRun run) {
         CTSimpleField ctField = run.getCTField();
@@ -1838,8 +1812,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
 
     /**
      * returns the type of the BodyElement Paragraph
-     *
-     * @see org.apache.poi.xwpf.usermodel.IBodyElement#getElementType()
      */
     @Override
     public BodyElementType getElementType() {
@@ -1876,8 +1848,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
 
     /**
      * adds a new Run to the Paragraph
-     *
-     * @param r
      */
     public void addRun(XWPFRun r) {
         if (!runs.contains(r)) {
@@ -1887,8 +1857,6 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para
 
     /**
      * return the XWPFRun-Element which owns the CTR run-Element
-     *
-     * @param r
      */
     public XWPFRun getRun(CTR r) {
         for (int i = 0; i < getRuns().size(); i++) {
diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSettings.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSettings.java
index 8df9e3f806..072a48a091 100644
--- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSettings.java
+++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSettings.java
@@ -73,9 +73,9 @@ public class XWPFSettings extends POIXMLDocumentPart {
      * it sets the value of zoom
      * <br>
      * sample snippet from settings.xml
-     * <pre>
-     *    &lt;w:zoom w:percent="50" /&gt;
-     * <pre>
+     * <pre>{@code
+     *    <w:zoom w:percent="50" />
+     * }</pre>
      *
      * @return percentage as an integer of zoom level
      */
@@ -97,9 +97,9 @@ public class XWPFSettings extends POIXMLDocumentPart {
      * it sets the value of zoom
      * <br>
      * sample snippet from settings.xml
-     * <pre>
-     *    &lt;w:zoom w:percent="50" /&gt;
-     * <pre>
+     * <pre>{@code
+     *    <w:zoom w:percent="50" />
+     * }</pre>
      */
     public void setZoomPercent(long zoomPercent) {
         if (!ctSettings.isSetZoom()) {
@@ -365,7 +365,7 @@ public class XWPFSettings extends POIXMLDocumentPart {
     /**
      * Check if revision tracking is turned on.
      *
-     * @return <code>true</code> if revision tracking is turned on
+     * @return {@code true} if revision tracking is turned on
      */
     public boolean isTrackRevisions() {
         return ctSettings.isSetTrackRevisions();
@@ -374,7 +374,7 @@ public class XWPFSettings extends POIXMLDocumentPart {
     /**
      * Enable or disable revision tracking.
      *
-     * @param enable <code>true</code> to  turn on revision tracking, <code>false</code> to turn off revision tracking
+     * @param enable {@code true} to  turn on revision tracking, {@code false} to turn off revision tracking
      */
     public void setTrackRevisions(boolean enable) {
         if (enable) {
@@ -432,8 +432,8 @@ public class XWPFSettings extends POIXMLDocumentPart {
     /**
      * Turn separate even-and-odd headings on or off
      *
-     * @param enable <code>true</code> to turn on separate even and odd headings,
-     * <code>false</code> to turn off even and odd headings.
+     * @param enable {@code true} to turn on separate even and odd headings,
+     * {@code false} to turn off even and odd headings.
      */
     public void setEvenAndOddHeadings(boolean enable) {
         CTOnOff onOff = CTOnOff.Factory.newInstance();
@@ -453,8 +453,8 @@ public class XWPFSettings extends POIXMLDocumentPart {
     /**
      * Turn mirrored margins on or off
      *
-     * @param enable <code>true</code> to turn on mirrored margins,
-     * <code>false</code> to turn off mirrored marginss.
+     * @param enable {@code true} to turn on mirrored margins,
+     * {@code false} to turn off mirrored marginss.
      */
     public void setMirrorMargins(boolean enable) {
         CTOnOff onOff = CTOnOff.Factory.newInstance();