fix javadocs

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

8 files changed, 64 insertions, 55 deletions

diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/HeadersFootersAtom.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/HeadersFootersAtom.java
index 9d51daa0fc..049776f5e2 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/HeadersFootersAtom.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/HeadersFootersAtom.java
@@ -129,15 +129,15 @@ public final class HeadersFootersAtom extends RecordAtom {
     /**
      * record header
      */
-    private byte[] _header;
+    private final byte[] _header;
 
 	/**
      * record data
      */
-	private byte[] _recdata;
+	private final byte[] _recdata;
 
     /**
-     * Build an instance of <code>HeadersFootersAtom</code> from on-disk data
+     * Build an instance of {@code HeadersFootersAtom} from on-disk data
      */
 	protected HeadersFootersAtom(byte[] source, int start, int len) {
 		// Get the header
@@ -148,7 +148,7 @@ public final class HeadersFootersAtom extends RecordAtom {
 	}
 
     /**
-     * Create a new instance of <code>HeadersFootersAtom</code>
+     * Create a new instance of {@code HeadersFootersAtom}
      */
     public HeadersFootersAtom() {
         _recdata = new byte[4];
@@ -158,6 +158,7 @@ public final class HeadersFootersAtom extends RecordAtom {
         LittleEndian.putInt(_header, 4, _recdata.length);
     }
 
+    @Override
     public long getRecordType() {
         return RecordTypes.HeadersFootersAtom.typeID;
     }
@@ -165,7 +166,8 @@ public final class HeadersFootersAtom extends RecordAtom {
     /**
 	 * Write the contents of the record back, so it can be written to disk
 	 */
-	public void writeOut(OutputStream out) throws IOException {
+	@Override
+    public void writeOut(OutputStream out) throws IOException {
 		out.write(_header);
 		out.write(_recdata);
 	}
@@ -173,10 +175,9 @@ public final class HeadersFootersAtom extends RecordAtom {
     /**
      * A signed integer that specifies the format ID to be used to style the datetime.
      * <p>
-     * It MUST be in the range [0, 12]. </br>
+     * It MUST be in the range [0, 12]. <p>
      * This value is converted into a string as specified by the index field of the DateTimeMCAtom record.
      * It MUST be ignored unless fHasTodayDate is TRUE.
-     * </b>
      *
      * @return  A signed integer that specifies the format ID to be used to style the datetime.
      */
@@ -196,6 +197,7 @@ public final class HeadersFootersAtom extends RecordAtom {
     /**
      *  A bit mask specifying options for displaying headers and footers
      *
+     * <ul>
      * <li> A - {@link #fHasDate} (1 bit): A bit that specifies whether the date is displayed in the footer.
      * <li> B - {@link #fHasTodayDate} (1 bit): A bit that specifies whether the current datetime is used for
      *      displaying the datetime.
@@ -207,6 +209,7 @@ public final class HeadersFootersAtom extends RecordAtom {
      * <li> F - {@link #fHasFooter} (1 bit): A bit that specifies whether the footer text specified by FooterAtom
      *      record is displayed.
      * <li> reserved (10 bits): MUST be zero and MUST be ignored.
+     * </ul>
      *
      * @return A bit mask specifying options for displaying headers and footers
      */
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/InteractiveInfoAtom.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/InteractiveInfoAtom.java
index 5b60c632fc..e5e5ccbb6c 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/InteractiveInfoAtom.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/InteractiveInfoAtom.java
@@ -121,12 +121,12 @@ public class InteractiveInfoAtom extends RecordAtom {
     /**
      * Record header.
      */
-    private byte[] _header;
+    private final byte[] _header;
 
     /**
      * Record data.
      */
-    private byte[] _data;
+    private final byte[] _data;
 
     /**
      * Constructs a brand new link related atom record.
@@ -203,7 +203,7 @@ public class InteractiveInfoAtom extends RecordAtom {
     /**
      * Hyperlink Action.
      * <p>
-     * see <code>ACTION_*</code> constants for the list of actions
+     * see {@code ACTION_*} constants for the list of actions
      * </p>
      *
      * @return hyperlink action.
@@ -215,7 +215,7 @@ public class InteractiveInfoAtom extends RecordAtom {
     /**
      * Hyperlink Action
      * <p>
-     * see <code>ACTION_*</code> constants for the list of actions
+     * see {@code ACTION_*} constants for the list of actions
      * </p>
      *
      * @param val hyperlink action.
@@ -241,7 +241,7 @@ public class InteractiveInfoAtom extends RecordAtom {
     /**
      * Jump
      * <p>
-     * see <code>JUMP_*</code> constants for the list of actions
+     * see {@code JUMP_*} constants for the list of actions
      * </p>
      *
      * @return jump
@@ -253,7 +253,7 @@ public class InteractiveInfoAtom extends RecordAtom {
     /**
      * Jump
      * <p>
-     * see <code>JUMP_*</code> constants for the list of actions
+     * see {@code JUMP_*} constants for the list of actions
      * </p>
      *
      * @param val jump
@@ -264,12 +264,12 @@ public class InteractiveInfoAtom extends RecordAtom {
 
     /**
      * Flags
-     * <p>
+     * <ul>
      * <li> Bit 1: Animated. If 1, then button is animated
      * <li> Bit 2: Stop sound. If 1, then stop current sound when button is pressed.
      * <li> Bit 3: CustomShowReturn. If 1, and this is a jump to custom show,
      *   then return to this slide after custom show.
-     * </p>
+     * </ul>
      */
     public byte getFlags() {
         return _data[11];
@@ -277,12 +277,12 @@ public class InteractiveInfoAtom extends RecordAtom {
 
     /**
      * Flags
-     * <p>
+     * <ul>
      * <li> Bit 1: Animated. If 1, then button is animated
      * <li> Bit 2: Stop sound. If 1, then stop current sound when button is pressed.
      * <li> Bit 3: CustomShowReturn. If 1, and this is a jump to custom show,
      *   then return to this slide after custom show.
-     * </p>
+     * </ul>
      */
     public void setFlags(byte val) {
     	_data[11] = val;
@@ -310,6 +310,7 @@ public class InteractiveInfoAtom extends RecordAtom {
      * Gets the record type.
      * @return the record type.
      */
+    @Override
     public long getRecordType() { return RecordTypes.InteractiveInfoAtom.typeID; }
 
     /**
@@ -319,6 +320,7 @@ public class InteractiveInfoAtom extends RecordAtom {
      * @param out the output stream to write to.
      * @throws IOException if an error occurs.
      */
+    @Override
     public void writeOut(OutputStream out) throws IOException {
         out.write(_header);
         out.write(_data);
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/SSSlideInfoAtom.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/SSSlideInfoAtom.java
index 7bd098f92b..0836ce98f1 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/SSSlideInfoAtom.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/record/SSSlideInfoAtom.java
@@ -38,7 +38,7 @@ import org.apache.poi.util.LittleEndianConsts;
  * <br>
  *
  * Combination of effectType and effectDirection:
- * <table>
+ * <table summary="">
  * <tr><th>type</th><th>description</th><th>direction</th></tr>
  * <tr><td>0</td><td>cut</td><td>0x00 = no transition, 0x01 = black transition</td></tr>
  * <tr><td>1</td><td>random</td><td>0x00</td></tr>
@@ -137,7 +137,7 @@ public class SSSlideInfoAtom extends RecordAtom {
 
     private static final long _type = RecordTypes.SSSlideInfoAtom.typeID;
 
-    private byte[] _header;
+    private final byte[] _header;
 
     /**
      * A signed integer that specifies an amount of time, in milliseconds, to wait
@@ -175,7 +175,7 @@ public class SSSlideInfoAtom extends RecordAtom {
      * (0x00 = 0.75 seconds, 0x01 = 0.5 seconds, 0x02 = 0.25 seconds)
      */
     private short _speed; // byte
-    private byte[] _unused; // 3-byte
+    private final byte[] _unused; // 3-byte
 
     public SSSlideInfoAtom() {
         _header = new byte[8];
@@ -222,6 +222,7 @@ public class SSSlideInfoAtom extends RecordAtom {
      * Write the contents of the record back, so it can be written
      *  to disk
      */
+    @Override
     public void writeOut(OutputStream out) throws IOException {
         // Header - size or type unchanged
         out.write(_header);
@@ -245,6 +246,7 @@ public class SSSlideInfoAtom extends RecordAtom {
     /**
      * We are of type 1017
      */
+    @Override
     public long getRecordType() { return _type; }
 
 
@@ -290,8 +292,6 @@ public class SSSlideInfoAtom extends RecordAtom {
 
     /**
      * Use one of the bitmasks MANUAL_ADVANCE_BIT ... CURSOR_VISIBLE_BIT
-     * @param bitmask
-     * @param enabled
      */
     public void setEffectTransitionFlagByBit(int bitmask, boolean enabled) {
         if (enabled) {
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFHyperlink.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFHyperlink.java
index 5575d16bb7..be27af04fe 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFHyperlink.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFHyperlink.java
@@ -50,15 +50,15 @@ public final class HSLFHyperlink implements Hyperlink<HSLFShape,HSLFTextParagrap
     public ExHyperlink getExHyperlink() {
         return exHyper;
     }
-    
+
     public InteractiveInfo getInfo() {
         return info;
     }
-    
+
     public TxInteractiveInfoAtom getTextRunInfo() {
         return txinfo;
     }
-    
+
     protected void setTextRunInfo(TxInteractiveInfoAtom txinfo) {
         this.txinfo = txinfo;
     }
@@ -69,7 +69,7 @@ public final class HSLFHyperlink implements Hyperlink<HSLFShape,HSLFTextParagrap
      *
      * @param shape the shape which receives the hyperlink
      * @return the new hyperlink
-     * 
+     *
      * @see HSLFSimpleShape#createHyperlink()
      */
     /* package */ static HSLFHyperlink createHyperlink(HSLFSimpleShape shape) {
@@ -94,7 +94,7 @@ public final class HSLFHyperlink implements Hyperlink<HSLFShape,HSLFTextParagrap
      *
      * @param run the run which receives the hyperlink
      * @return the new hyperlink
-     * 
+     *
      * @see HSLFTextRun#createHyperlink()
      */
     /* package */ static HSLFHyperlink createHyperlink(HSLFTextRun run) {
@@ -109,22 +109,22 @@ public final class HSLFHyperlink implements Hyperlink<HSLFShape,HSLFTextParagrap
         // this will be done, when the paragraph is saved
         HSLFHyperlink hyper = new HSLFHyperlink(exHyper, info);
         hyper.linkToNextSlide();
-        
+
         TxInteractiveInfoAtom txinfo = new TxInteractiveInfoAtom();
         int startIdx = run.getTextParagraph().getStartIdxOfTextRun(run);
         int endIdx = startIdx + run.getLength();
         txinfo.setStartIndex(startIdx);
         txinfo.setEndIndex(endIdx);
         hyper.setTextRunInfo(txinfo);
-        
+
         run.setHyperlink(hyper);
         return hyper;
     }
-    
+
 
     /**
      * Gets the type of the hyperlink action.
-     * Must be a <code>LINK_*</code>  constant</code>
+     * Must be a {@code LINK_*} constant
      *
      * @return the hyperlink URL
      * @see InteractiveInfoAtom
@@ -300,8 +300,8 @@ public final class HSLFHyperlink implements Hyperlink<HSLFShape,HSLFTextParagrap
     /**
      * Find hyperlinks in a text shape
      *
-     * @param shape  <code>TextRun</code> to lookup hyperlinks in
-     * @return found hyperlinks or <code>null</code> if not found
+     * @param shape  {@code TextRun} to lookup hyperlinks in
+     * @return found hyperlinks or {@code null} if not found
      */
     public static List<HSLFHyperlink> find(HSLFTextShape shape){
         return find(shape.getTextParagraphs());
@@ -310,7 +310,7 @@ public final class HSLFHyperlink implements Hyperlink<HSLFShape,HSLFTextParagrap
     /**
      * Find hyperlinks in a text paragraph
      *
-     * @param paragraphs  List of <code>TextParagraph</code> to lookup hyperlinks
+     * @param paragraphs  List of {@code TextParagraph} to lookup hyperlinks
      * @return found hyperlinks
      */
     @SuppressWarnings("resource")
@@ -334,8 +334,8 @@ public final class HSLFHyperlink implements Hyperlink<HSLFShape,HSLFTextParagrap
     /**
      * Find hyperlink assigned to the supplied shape
      *
-     * @param shape  <code>Shape</code> to lookup hyperlink in
-     * @return found hyperlink or <code>null</code>
+     * @param shape  {@code Shape} to lookup hyperlink in
+     * @return found hyperlink or {@code null}
      */
     @SuppressWarnings("resource")
     protected static HSLFHyperlink find(HSLFShape shape){
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfBinaryRasterOp.java b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfBinaryRasterOp.java
index 5325931dbe..cf50d43719 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfBinaryRasterOp.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfBinaryRasterOp.java
@@ -29,14 +29,14 @@ import java.util.function.BiConsumer;
  * selected pen and the destination bitmap are combined. Following are the two operands used in these
  * operations.
  *
- * <table>
+ * <table summary="">
  * <tr><th>Operand</th><th>Meaning</th></tr>
  * <tr><td>P</td><td>Selected pen</td></tr>
  * <tr><td>D</td><td>Destination bitmap</td></tr>
  * </table>
  *
  * Following are the Boolean operators used in these operations.
- * <table>
+ * <table summary="">
  * <tr><th>Operand</th><th>Meaning</th></tr>
  * <tr><td>a</td><td>Bitwise AND</td></tr>
  * <tr><td>n</td><td>Bitwise NOT (inverse)</td></tr>
@@ -54,7 +54,7 @@ import java.util.function.BiConsumer;
  * (in this case, the pen and destination values). For example, the operation indexes for the DPo and
  * DPan operations are shown in the following list.
  *
- * <table>
+ * <table summary="">
  * <tr><th>P</th><th>D</th><th>DPo</th><th>DPan</th></tr>
  * <tr><td>0</td><td>0</td><td>0</td><td>1</td></tr>
  * <tr><td>0</td><td>1</td><td>1</td><td>1</td></tr>
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfMisc.java b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfMisc.java
index b4ecc2fc3c..df252a35c1 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfMisc.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfMisc.java
@@ -72,10 +72,12 @@ public class HwmfMisc {
      * The META_SETRELABS record is reserved and not supported.
      */
     public static class WmfSetRelabs implements HwmfRecord {
+        @Override
         public HwmfRecordType getWmfRecordType() {
             return HwmfRecordType.setRelabs;
         }
 
+        @Override
         public int init(LittleEndianInputStream leis, long recordSize, int recordFunction) throws IOException {
             return 0;
         }
@@ -186,7 +188,7 @@ public class HwmfMisc {
         public enum HwmfBkMode {
             TRANSPARENT(0x0001), OPAQUE(0x0002);
 
-            int flag;
+            final int flag;
             HwmfBkMode(int flag) {
                 this.flag = flag;
             }
@@ -201,10 +203,12 @@ public class HwmfMisc {
 
         protected HwmfBkMode bkMode;
 
+        @Override
         public HwmfRecordType getWmfRecordType() {
             return HwmfRecordType.setBkMode;
         }
 
+        @Override
         public int init(LittleEndianInputStream leis, long recordSize, int recordFunction) throws IOException {
             bkMode = HwmfBkMode.valueOf(leis.readUShort());
             return LittleEndianConsts.SHORT_SIZE;
@@ -752,7 +756,7 @@ public class HwmfMisc {
      * The following table shows the relationship between values in the BrushStyle,
      * ColorRef and BrushHatch fields in a LogBrush Object. Only supported brush styles are listed.
      *
-     * <table>
+     * <table summary="">
      * <tr>
      *   <th>BrushStyle</th>
      *   <th>ColorRef</th>
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfTernaryRasterOp.java b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfTernaryRasterOp.java
index 2f79af4087..c84601e2b1 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfTernaryRasterOp.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hwmf/record/HwmfTernaryRasterOp.java
@@ -25,7 +25,7 @@ import java.util.Deque;
  * the source, the selected brush, and the destination are combined. Following are the three operands
  * used in these operations.
  *
- * <table>
+ * <table summary="">
  * <tr><th>Operand</th><th>Meaning</th></tr>
  * <tr><td>D</td><td>Destination bitmap</td></tr>
  * <tr><td>P</td><td>Selected brush (also called pattern)</td></tr>
@@ -33,7 +33,7 @@ import java.util.Deque;
  * </table>
  *
  * Following are the Boolean operators used in these operations.
- * <table>
+ * <table summary="">
  * <tr><th>Operand</th><th>Meaning</th></tr>
  * <tr><td>a</td><td>Bitwise AND</td></tr>
  * <tr><td>n</td><td>Bitwise NOT (inverse)</td></tr>
@@ -55,7 +55,7 @@ import java.util.Deque;
  * values. For example, the operation indexes for the PSo and DPSoo operations are shown in the
  * following list.
  *
- * <table>
+ * <table summary="">
  * <tr><th>P</th><th>S</th><th>D</th><th>DPo</th><th>DPan</th></tr>
  * <tr><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td></tr>
  * <tr><td>0</td><td>0</td><td>1</td><td>0</td><td>1</td></tr>
diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/model/types/HRESIAbstractType.java b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/model/types/HRESIAbstractType.java
index d4e410e2a3..82d5201354 100644
--- a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/model/types/HRESIAbstractType.java
+++ b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/model/types/HRESIAbstractType.java
@@ -67,21 +67,19 @@ public abstract class HRESIAbstractType {
 
     public String toString()
     {
-        StringBuilder builder = new StringBuilder();
-        builder.append("[HRESI]\n");
-        builder.append("    .hres                 = ");
-        builder.append(" (").append(getHres()).append(" )\n");
-        builder.append("    .chHres               = ");
-        builder.append(" (").append(getChHres()).append(" )\n");
-
-        builder.append("[/HRESI]\n");
-        return builder.toString();
+        return "[HRESI]\n" +
+            "    .hres                 = " +
+            " (" + getHres() + " )\n" +
+            "    .chHres               = " +
+            " (" + getChHres() + " )\n" +
+            "[/HRESI]\n";
     }
 
     /**
      * Hyphenation rule.
      *
      * @return One of
+     * <ul>
      * <li>{@link #HRES_NO}
      * <li>{@link #HRES_NORMAL}
      * <li>{@link #HRES_ADD_LETTER_BEFORE}
@@ -89,6 +87,7 @@ public abstract class HRESIAbstractType {
      * <li>{@link #HRES_DELETE_LETTER_BEFORE}
      * <li>{@link #HRES_CHANGE_LETTER_AFTER}
      * <li>{@link #HRES_DELETE_BEFORE_CHANGE_BEFORE}
+     * </ul>
      */
     public byte getHres()
     {
@@ -98,8 +97,8 @@ public abstract class HRESIAbstractType {
     /**
      * Hyphenation rule.
      *
-     * @param field_1_hres
-     *        One of
+     * @param field_1_hres One of
+     * <ul>
      * <li>{@link #HRES_NO}
      * <li>{@link #HRES_NORMAL}
      * <li>{@link #HRES_ADD_LETTER_BEFORE}
@@ -107,6 +106,7 @@ public abstract class HRESIAbstractType {
      * <li>{@link #HRES_DELETE_LETTER_BEFORE}
      * <li>{@link #HRES_CHANGE_LETTER_AFTER}
      * <li>{@link #HRES_DELETE_BEFORE_CHANGE_BEFORE}
+     * </ul>
      */
     public void setHres( byte field_1_hres )
     {