Merge branch 'develop' into devsecops

itext/itext.kernel/itext/kernel/actions/events/LinkDocumentIdEvent.cs

@@ -28,7 +28,7 @@ You should have received a copy of the GNU Affero General Public License
 
 namespace iText.Kernel.Actions.Events {
     /// <summary>
-    /// An event allows to associated some
+    /// An event allows to associate some
     /// <see cref="iText.Commons.Actions.Sequence.SequenceId"/>
     /// with
     /// <see cref="iText.Kernel.Pdf.PdfDocument"/>.

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

@@ -116,6 +116,11 @@ public class CompareTool {
 
         private String compareExec;
 
+        /// <summary>
+        /// Create new
+        /// <see cref="CompareTool"/>
+        /// instance.
+        /// </summary>
         public CompareTool() {
         }
 
@@ -1691,6 +1696,20 @@ private PdfNumber FlattenNumTree(PdfDictionary dictionary, PdfNumber leftOver, L
             return null;
         }
 
+        /// <summary>Compare PDF objects.</summary>
+        /// <param name="outObj">out object corresponding to the output file, which is to be compared with cmp object</param>
+        /// <param name="cmpObj">cmp object corresponding to the cmp-file, which is to be compared with out object</param>
+        /// <param name="currentPath">
+        /// current objects
+        /// <see cref="iText.Kernel.Utils.Objectpathitems.ObjectPath"/>
+        /// path
+        /// </param>
+        /// <param name="compareResult">
+        /// 
+        /// <see cref="CompareResult"/>
+        /// for the results of the comparison of the two documents
+        /// </param>
+        /// <returns>true if objects are equal, false otherwise.</returns>
         protected internal virtual bool CompareObjects(PdfObject outObj, PdfObject cmpObj, ObjectPath currentPath, 
             CompareTool.CompareResult compareResult) {
             PdfObject outDirectObj = null;
@@ -2281,10 +2300,23 @@ public virtual void WriteReportToXml(Stream stream) {
                 XmlUtils.WriteXmlDocToStream(xmlReport, stream);
             }
 
+            /// <summary>Checks whether maximum number of difference messages to be handled by this CompareResult is reached.
+            ///     </summary>
+            /// <returns>true if limit of difference messages is reached, false otherwise.</returns>
             protected internal virtual bool IsMessageLimitReached() {
                 return differences.Count >= messageLimit;
             }
 
+            /// <summary>
+            /// Adds an error message for the
+            /// <see cref="iText.Kernel.Utils.Objectpathitems.ObjectPath"/>.
+            /// </summary>
+            /// <param name="path">
+            /// 
+            /// <see cref="iText.Kernel.Utils.Objectpathitems.ObjectPath"/>
+            /// for the two corresponding objects in the compared documents
+            /// </param>
+            /// <param name="message">an error message</param>
             protected internal virtual void AddError(ObjectPath path, String message) {
                 if (differences.Count < messageLimit) {
                     differences.Put(new ObjectPath(path), message);

itext/itext.kernel/itext/kernel/utils/PageRange.cs

@@ -37,7 +37,7 @@ public class PageRange {
 
         private static readonly Regex SINGLE_PAGE_PATTERN = iText.Commons.Utils.StringUtil.RegexCompile("(\\d+)");
 
-        private IList<PageRange.IPageRangePart> sequences = new List<PageRange.IPageRangePart>();
+        private readonly IList<PageRange.IPageRangePart> sequences = new List<PageRange.IPageRangePart>();
 
         /// <summary>
         /// Constructs an empty
@@ -208,15 +208,30 @@ public override int GetHashCode() {
         /// <summary>Inner interface for range parts definition</summary>
         public interface IPageRangePart {
             //public List<Integer> getAllPages();
+            /// <summary>Gets the list of pages that have been added to the range part so far.</summary>
+            /// <param name="nbPages">
+            /// number of pages of the document to get the pages,
+            /// to list only the pages eligible for this document
+            /// </param>
+            /// <returns>the list containing page numbers added to the range part matching this document</returns>
             IList<int> GetAllPagesInRange(int nbPages);
 
+            /// <summary>Checks if a given page is present in the range part built so far.</summary>
+            /// <param name="pageNumber">the page number to check</param>
+            /// <returns><c>true</c> if the page is present in this range, <c>false</c> otherwise</returns>
             bool IsPageInRange(int pageNumber);
         }
 
-        /// <summary>Class for range part containing a single page</summary>
+        /// <summary>Class for range part containing a single page.</summary>
         public class PageRangePartSingle : PageRange.IPageRangePart {
             private readonly int page;
 
+            /// <summary>
+            /// Creates new
+            /// <see cref="PageRangePartSingle"/>
+            /// instance.
+            /// </summary>
+            /// <param name="page">a single page for a range part</param>
             public PageRangePartSingle(int page) {
                 this.page = page;
             }
@@ -251,13 +266,20 @@ public override int GetHashCode() {
 
         /// <summary>
         /// Class for range part containing a range of pages represented by a start
-        /// and an end page
+        /// and an end page.
         /// </summary>
         public class PageRangePartSequence : PageRange.IPageRangePart {
             private readonly int start;
 
             private readonly int end;
 
+            /// <summary>
+            /// Creates new
+            /// <see cref="PageRangePartSequence"/>
+            /// instance.
+            /// </summary>
+            /// <param name="start">the number of the first page in a range part</param>
+            /// <param name="end">the number of the last page in a range part</param>
             public PageRangePartSequence(int start, int end) {
                 this.start = start;
                 this.end = end;
@@ -292,11 +314,17 @@ public override int GetHashCode() {
 
         /// <summary>
         /// Class for range part containing a range of pages for all pages after a
-        /// given start page
+        /// given start page.
         /// </summary>
         public class PageRangePartAfter : PageRange.IPageRangePart {
             private readonly int start;
 
+            /// <summary>
+            /// Creates new
+            /// <see cref="PageRangePartAfter"/>
+            /// instance.
+            /// </summary>
+            /// <param name="start">the number of the first page in a range part</param>
             public PageRangePartAfter(int start) {
                 this.start = start;
             }
@@ -391,6 +419,17 @@ public override int GetHashCode() {
         public class PageRangePartAnd : PageRange.IPageRangePart {
             private readonly IList<PageRange.IPageRangePart> conditions = new List<PageRange.IPageRangePart>();
 
+            /// <summary>
+            /// Creates new
+            /// <see cref="PageRangePartAnd"/>
+            /// instance.
+            /// </summary>
+            /// <param name="conditions">
+            /// 
+            /// <see cref="IPageRangePart"/>
+            /// conditions to combine several range parts,
+            /// e.g. to configure odd pages between page 19 and 25
+            /// </param>
             public PageRangePartAnd(params PageRange.IPageRangePart[] conditions) {
                 this.conditions.AddAll(JavaUtil.ArraysAsList(conditions));
             }

itext/itext.kernel/itext/kernel/utils/PdfMerger.cs

@@ -25,6 +25,7 @@ You should have received a copy of the GNU Affero General Public License
 using iText.Kernel.Pdf;
 
 namespace iText.Kernel.Utils {
+    /// <summary>Helper class to merge a number of existing documents into one.</summary>
     public class PdfMerger {
         private PdfDocument pdfDocument;
 

itext/itext.kernel/itext/kernel/utils/PdfSplitter.cs

@@ -29,6 +29,7 @@ You should have received a copy of the GNU Affero General Public License
 using iText.Kernel.Pdf;
 
 namespace iText.Kernel.Utils {
+    /// <summary>Helper class to split the document based on some condition.</summary>
     public class PdfSplitter {
         private PdfDocument pdfDocument;
 
@@ -192,6 +193,12 @@ public virtual PdfDocument ExtractPageRange(PageRange pageRange) {
             return ExtractPageRanges(JavaCollectionsUtil.SingletonList(pageRange))[0];
         }
 
+        /// <summary>Gets the document to be split.</summary>
+        /// <returns>
+        /// 
+        /// <see cref="iText.Kernel.Pdf.PdfDocument"/>
+        /// to be split.
+        /// </returns>
         public virtual PdfDocument GetPdfDocument() {
             return pdfDocument;
         }
@@ -224,7 +231,11 @@ private PdfDocument CreatePdfDocument(PageRange currentPageRange) {
             return newDocument;
         }
 
+        /// <summary>The event listener which is called when another document is ready.</summary>
         public interface IDocumentReadyListener {
+            /// <summary>Performs some action in case document is ready, e.g. closes the document.</summary>
+            /// <param name="pdfDocument">the current document created as a result of the original document split</param>
+            /// <param name="pageRange">original document page range corresponding to the current document</param>
             void DocumentReady(PdfDocument pdfDocument, PageRange pageRange);
         }
 

itext/itext.kernel/itext/kernel/utils/TaggedPdfReaderTool.cs

@@ -59,7 +59,7 @@ public TaggedPdfReaderTool(PdfDocument document) {
 
         /// <summary>Checks if a character value should be escaped/unescaped.</summary>
         /// <param name="c">a character value</param>
-        /// <returns>true if it's OK to escape or unescape this value</returns>
+        /// <returns>true if it's OK to escape or unescape this value.</returns>
         public static bool IsValidCharacterValue(int c) {
             return (c == 0x9 || c == 0xA || c == 0xD || c >= 0x20 && c <= 0xD7FF || c >= 0xE000 && c <= 0xFFFD || c >=
                  0x10000 && c <= 0x10FFFF);
@@ -101,6 +101,8 @@ public virtual iText.Kernel.Utils.TaggedPdfReaderTool SetRootTag(String rootTagN
             return this;
         }
 
+        /// <summary>Inspect the children of the StructTreeRoot.</summary>
+        /// <param name="kids">list of the direct kids of the StructTreeRoot</param>
         protected internal virtual void InspectKids(IList<IStructureNode> kids) {
             if (kids == null) {
                 return;
@@ -110,6 +112,8 @@ protected internal virtual void InspectKids(IList<IStructureNode> kids) {
             }
         }
 
+        /// <summary>Inspect the child of the StructTreeRoot.</summary>
+        /// <param name="kid">the direct kid of the StructTreeRoot</param>
         protected internal virtual void InspectKid(IStructureNode kid) {
             try {
                 if (kid is PdfStructElem) {
@@ -146,6 +150,8 @@ protected internal virtual void InspectKid(IStructureNode kid) {
             }
         }
 
+        /// <summary>Inspects attributes dictionary of the StructTreeRoot child.</summary>
+        /// <param name="kid">the direct kid of the StructTreeRoot</param>
         protected internal virtual void InspectAttributes(PdfStructElem kid) {
             PdfObject attrObj = kid.GetAttributes(false);
             if (attrObj != null) {
@@ -172,6 +178,12 @@ protected internal virtual void InspectAttributes(PdfStructElem kid) {
             }
         }
 
+        /// <summary>Parses tag of the Marked Content Reference (MCR) kid of the StructTreeRoot.</summary>
+        /// <param name="kid">
+        /// the direct
+        /// <see cref="iText.Kernel.Pdf.Tagging.PdfMcr"/>
+        /// kid of the StructTreeRoot
+        /// </param>
         protected internal virtual void ParseTag(PdfMcr kid) {
             int mcid = kid.GetMcid();
             PdfDictionary pageDic = kid.GetPageObject();
@@ -205,6 +217,9 @@ protected internal virtual void ParseTag(PdfMcr kid) {
             }
         }
 
+        /// <summary>Fixes specified tag name to be valid XML tag.</summary>
+        /// <param name="tag">tag name to fix</param>
+        /// <returns>fixed tag name.</returns>
         protected internal static String FixTagName(String tag) {
             StringBuilder sb = new StringBuilder();
             for (int k = 0; k < tag.Length; ++k) {

itext/itext.kernel/itext/kernel/utils/ValidationContext.cs

@@ -35,23 +35,72 @@ public class ValidationContext {
 
         private ICollection<PdfFont> fonts = null;
 
+        /// <summary>
+        /// Creates new
+        /// <see cref="ValidationContext"/>
+        /// instance.
+        /// </summary>
         public ValidationContext() {
         }
 
+        /// <summary>
+        /// Sets
+        /// <see cref="iText.Kernel.Pdf.PdfDocument"/>
+        /// for this
+        /// <see cref="ValidationContext"/>
+        /// instance.
+        /// </summary>
+        /// <param name="pdfDocument">document to validate.</param>
+        /// <returns>
+        /// this
+        /// <see cref="ValidationContext"/>
+        /// instance.
+        /// </returns>
         public virtual iText.Kernel.Utils.ValidationContext WithPdfDocument(PdfDocument pdfDocument) {
             this.PdfDocument = pdfDocument;
             return this;
         }
 
+        /// <summary>
+        /// Sets fonts for this
+        /// <see cref="ValidationContext"/>
+        /// instance.
+        /// </summary>
+        /// <param name="fonts">
+        /// collection of the
+        /// <see cref="iText.Kernel.Font.PdfFont"/>
+        /// fonts to validate.
+        /// </param>
+        /// <returns>
+        /// this
+        /// <see cref="ValidationContext"/>
+        /// instance.
+        /// </returns>
         public virtual iText.Kernel.Utils.ValidationContext WithFonts(ICollection<PdfFont> fonts) {
             this.fonts = fonts;
             return this;
         }
 
+        /// <summary>
+        /// Gets
+        /// <see cref="iText.Kernel.Pdf.PdfDocument"/>
+        /// related to this
+        /// <see cref="ValidationContext"/>.
+        /// </summary>
+        /// <returns>
+        /// 
+        /// <see cref="iText.Kernel.Pdf.PdfDocument"/>
+        /// document to validate.
+        /// </returns>
         public virtual PdfDocument GetPdfDocument() {
             return PdfDocument;
         }
 
+        /// <summary>
+        /// Gets fonts related to this
+        /// <see cref="ValidationContext"/>.
+        /// </summary>
+        /// <returns>fonts to validate.</returns>
         public virtual ICollection<PdfFont> GetFonts() {
             return fonts;
         }

itext/itext.kernel/itext/kernel/utils/annotationsflattening/PdfAnnotationFlattenFactory.cs

@@ -25,6 +25,7 @@ You should have received a copy of the GNU Affero General Public License
 using iText.Kernel.Pdf;
 
 namespace iText.Kernel.Utils.Annotationsflattening {
+    /// <summary>Helper class to retrieve the annotation flatten worker for the specified annotation subtype.</summary>
     public class PdfAnnotationFlattenFactory {
         private static readonly Dictionary<PdfName, Func<IAnnotationFlattener>> map;
 

itext/itext.kernel/itext/kernel/utils/objectpathitems/ObjectPath.cs

@@ -85,6 +85,17 @@ public ObjectPath(PdfIndirectReference baseCmpObject, PdfIndirectReference baseO
             indirects.Push(new IndirectPathItem(baseCmpObject, baseOutObject));
         }
 
+        /// <summary>Creates CompareObjectPath with corresponding base objects in two documents.</summary>
+        /// <param name="baseCmpObject">base object in cmp document</param>
+        /// <param name="baseOutObject">base object in out document</param>
+        /// <param name="path">
+        /// local path that denotes sequence of the path items from base object
+        /// to the comparing direct object
+        /// </param>
+        /// <param name="indirects">
+        /// indirect path which denotes sequence of the indirect references that
+        /// were passed in comparing process to get to the current base objects
+        /// </param>
         public ObjectPath(PdfIndirectReference baseCmpObject, PdfIndirectReference baseOutObject, Stack<LocalPathItem
             > path, Stack<IndirectPathItem> indirects) {
             this.baseCmpObject = baseCmpObject;