Improve StructTreeRoot documentation

DEVSIX-4812

Autoported commit.
Original commit hash: [1d4e2c754]

Author: yulian-gaponenko

itext/itext.kernel/itext/kernel/pdf/PdfDocument.cs

@@ -939,7 +939,7 @@ public virtual iText.Kernel.Pdf.PdfDocument SetTagged() {
         /// <returns>
         /// 
         /// <see cref="iText.Kernel.Pdf.Tagging.PdfStructTreeRoot"/>
-        /// in case tagged document, otherwise false.
+        /// in case document is tagged, otherwise it returns null.
         /// </returns>
         /// <seealso cref="IsTagged()"/>
         /// <seealso cref="GetNextStructParentIndex()"/>

itext/itext.kernel/itext/kernel/pdf/tagging/PdfStructTreeRoot.cs

@@ -51,28 +51,52 @@ source product.
 using iText.Kernel.Pdf.Filespec;
 
 namespace iText.Kernel.Pdf.Tagging {
+    /// <summary>Represents a wrapper-class for structure tree root dictionary.</summary>
+    /// <remarks>Represents a wrapper-class for structure tree root dictionary. See ISO-32000-1 "14.7.2 Structure hierarchy".
+    ///     </remarks>
     public class PdfStructTreeRoot : PdfObjectWrapper<PdfDictionary>, IStructureNode {
         private PdfDocument document;
 
         private ParentTreeHandler parentTreeHandler;
 
         private static IDictionary<String, PdfName> staticRoleNames = new ConcurrentDictionary<String, PdfName>();
 
+        /// <summary>Creates a new structure tree root instance, this initializes empty logical structure in the document.
+        ///     </summary>
+        /// <remarks>
+        /// Creates a new structure tree root instance, this initializes empty logical structure in the document.
+        /// This class also handles global state of parent tree, so it's not expected to create multiple instances
+        /// of this class. Instead, use
+        /// <see cref="iText.Kernel.Pdf.PdfDocument.GetStructTreeRoot()"/>.
+        /// </remarks>
+        /// <param name="document">a document to which new instance of struct tree root will be bound</param>
         public PdfStructTreeRoot(PdfDocument document)
             : this((PdfDictionary)new PdfDictionary().MakeIndirect(document), document) {
             GetPdfObject().Put(PdfName.Type, PdfName.StructTreeRoot);
         }
 
-        public PdfStructTreeRoot(PdfDictionary pdfObject, PdfDocument document)
-            : base(pdfObject) {
+        /// <summary>Creates wrapper instance for already existing logical structure tree root in the document.</summary>
+        /// <remarks>
+        /// Creates wrapper instance for already existing logical structure tree root in the document.
+        /// This class also handles global state of parent tree, so it's not expected to create multiple instances
+        /// of this class. Instead, use
+        /// <see cref="iText.Kernel.Pdf.PdfDocument.GetStructTreeRoot()"/>.
+        /// </remarks>
+        /// <param name="structTreeRootDict">a dictionary that defines document structure tree root</param>
+        /// <param name="document">a document, which contains given structure tree root dictionary</param>
+        public PdfStructTreeRoot(PdfDictionary structTreeRootDict, PdfDocument document)
+            : base(structTreeRootDict) {
             this.document = document;
             if (this.document == null) {
-                EnsureObjectIsAddedToDocument(pdfObject);
-                this.document = pdfObject.GetIndirectReference().GetDocument();
+                EnsureObjectIsAddedToDocument(structTreeRootDict);
+                this.document = structTreeRootDict.GetIndirectReference().GetDocument();
             }
             SetForbidRelease();
             parentTreeHandler = new ParentTreeHandler(this);
-            // TODO may be remove?
+            // Always init role map dictionary in order to avoid inconsistency, because
+            // iText often initializes it during role mapping resolution anyway.
+            // In future, better way might be to not write it to the document needlessly
+            // and avoid possible redundant modifications in append mode.
             GetRoleMap();
         }
 

port-hash

@@ -1 +1 @@
-9a47f5f698e7cfccda49810bff84abcd45368154
+f8771af2f52833c1c967a729a80ebb4d6b14056f