Reformat CompareTool javadocs, add details about diffPrefix arg to all overloads

ITXT-CR-749

Autoported commit.
Original commit hash: [bff5c021de]

Author: yulian-gaponenko

itext/itext.kernel/itext/kernel/utils/CompareTool.cs

@@ -469,8 +469,10 @@ public virtual String CompareByContent(String outPdf, String cmpPdf, String outP
         /// <param name="cmpPdf">the absolute path to the cmp-file, which is to be compared to output file.</param>
         /// <param name="outPath">the absolute path to the folder, which will be used to store image files for visual comparison.
         ///     </param>
-        /// <param name="differenceImagePrefix">file name prefix for image files with marked visual differences if there is any.
-        ///     </param>
+        /// <param name="differenceImagePrefix">
+        /// file name prefix for image files with marked visual differences if there is any;
+        /// if it's set to null the prefix defaults to diff_%outPdfFileName%_ format.
+        /// </param>
         /// <returns>
         /// string containing text report of the encountered content differences and also list of the pages that are
         /// visually different, or null if there are no content and therefore no visual differences.
@@ -517,8 +519,10 @@ public virtual String CompareByContent(String outPdf, String cmpPdf, String outP
         /// <param name="cmpPdf">the absolute path to the cmp-file, which is to be compared to output file.</param>
         /// <param name="outPath">the absolute path to the folder, which will be used to store image files for visual comparison.
         ///     </param>
-        /// <param name="differenceImagePrefix">file name prefix for image files with marked visual differences if there is any.
-        ///     </param>
+        /// <param name="differenceImagePrefix">
+        /// file name prefix for image files with marked visual differences if there is any;
+        /// if it's set to null the prefix defaults to diff_%outPdfFileName%_ format.
+        /// </param>
         /// <param name="outPass">password for the encrypted document specified by the outPdf absolute path.</param>
         /// <param name="cmpPass">password for the encrypted document specified by the cmpPdf absolute path.</param>
         /// <returns>
@@ -560,8 +564,10 @@ public virtual String CompareByContent(String outPdf, String cmpPdf, String outP
         /// <param name="cmpPdf">the absolute path to the cmp-file, which is to be compared to output file.</param>
         /// <param name="outPath">the absolute path to the folder, which will be used to store image files for visual comparison.
         ///     </param>
-        /// <param name="differenceImagePrefix">file name prefix for image files with marked visual differences if there is any.
-        ///     </param>
+        /// <param name="differenceImagePrefix">
+        /// file name prefix for image files with marked visual differences if there is any;
+        /// if it's set to null the prefix defaults to diff_%outPdfFileName%_ format.
+        /// </param>
         /// <param name="ignoredAreas">a map with one-based page numbers as keys and lists of ignored rectangles as values.
         ///     </param>
         /// <returns>
@@ -604,8 +610,10 @@ public virtual String CompareByContent(String outPdf, String cmpPdf, String outP
         /// <param name="cmpPdf">the absolute path to the cmp-file, which is to be compared to output file.</param>
         /// <param name="outPath">the absolute path to the folder, which will be used to store image files for visual comparison.
         ///     </param>
-        /// <param name="differenceImagePrefix">file name prefix for image files with marked visual differences if there is any.
-        ///     </param>
+        /// <param name="differenceImagePrefix">
+        /// file name prefix for image files with marked visual differences if there is any;
+        /// if it's set to null the prefix defaults to diff_%outPdfFileName%_ format.
+        /// </param>
         /// <param name="ignoredAreas">a map with one-based page numbers as keys and lists of ignored rectangles as values.
         ///     </param>
         /// <param name="outPass">password for the encrypted document specified by the outPdf absolute path.</param>
@@ -2430,12 +2438,6 @@ public override bool Equals(Object obj) {
                     return obj.GetType() == GetType() && key.Equals(((CompareTool.ObjectPath.DictPathItem)obj).key);
                 }
 
-                protected internal override XmlElement ToXmlNode(XmlDocument document) {
-                    XmlElement element = document.CreateElement("dictKey");
-                    element.AppendChild(document.CreateTextNode(key.ToString()));
-                    return element;
-                }
-
                 /// <summary>
                 /// The key which defines to which entry of the
                 /// <see cref="iText.Kernel.Pdf.PdfDictionary"/>
@@ -2453,6 +2455,12 @@ protected internal override XmlElement ToXmlNode(XmlDocument document) {
                 public virtual PdfName GetKey() {
                     return key;
                 }
+
+                protected internal override XmlElement ToXmlNode(XmlDocument document) {
+                    XmlElement element = document.CreateElement("dictKey");
+                    element.AppendChild(document.CreateTextNode(key.ToString()));
+                    return element;
+                }
             }
 
             /// <summary>
@@ -2492,12 +2500,6 @@ public override bool Equals(Object obj) {
                     return obj.GetType() == GetType() && index == ((CompareTool.ObjectPath.ArrayPathItem)obj).index;
                 }
 
-                protected internal override XmlElement ToXmlNode(XmlDocument document) {
-                    XmlElement element = document.CreateElement("arrayIndex");
-                    element.AppendChild(document.CreateTextNode(index.ToString()));
-                    return element;
-                }
-
                 /// <summary>
                 /// The index which defines element of the
                 /// <see cref="iText.Kernel.Pdf.PdfArray"/>
@@ -2510,6 +2512,12 @@ protected internal override XmlElement ToXmlNode(XmlDocument document) {
                 public virtual int GetIndex() {
                     return index;
                 }
+
+                protected internal override XmlElement ToXmlNode(XmlDocument document) {
+                    XmlElement element = document.CreateElement("arrayIndex");
+                    element.AppendChild(document.CreateTextNode(index.ToString()));
+                    return element;
+                }
             }
 
             /// <summary>

port-hash

@@ -1 +1 @@
-d1fb502b6ce201adef926ae458591c2a98191f09
+bff5c021deff1084c9900878ac6c85f983d82b76