Revize a35cb648

Added comments to backend

Backend/Core/Services/HTMLService/HTMLService.cs

@@ -13 +13 @@
 {
     public class HTMLService : IHTMLService
     {
-
+        /// <summary>
+        /// Attribute name for uniquely identifying each tag in the HTML document on the frontend
+        /// </summary>
         private const string TAG_ID_ATTRIBUTE_NAME = "aswi-tag-id";
+
+        /// <summary>
+        /// Attribute name for tag instance so that each marked out tag can be given a style
+        /// </summary>
         private const string TAG_INSTANCE_ATTRIBUTE_NAME = "aswi-tag-instance";
+
+        /// <summary>
+        /// Attribute name for EF Tag IDs so that the frontend can reference them to the backend for deletion
+        /// </summary>
         private const string TAG_EF_ID_ATTRIBUTE_NAME = "aswi-tag-ef-id";
 
+        /// <summary>
+        /// Info that is cached in tha database
+        /// </summary>
         public class CachedInfo
         {
+            /// <summary>
+            /// Positions of opening tags in the original HTML document
+            /// </summary>
             public List<int> TagStartPositions = new();
+            /// <summary>
+            /// Lengths of opening tags in the original HTML document
+            /// </summary>
             public List<int> TagStartLengths = new();
+            /// <summary>
+            /// Positions of closing tags in the original HTML document
+            /// </summary>
             public List<int> TagClosingPositions = new();
+            /// <summary>
+            /// Lengths for closing tags in the original HTML document
+            /// </summary>
             public List<int> TagClosingLengths = new();
+            /// <summary>
+            /// Unused
+            /// </summary>
             public Dictionary<HtmlNode, HtmlNode> NodeDict = new();
+            /// <summary>
+            /// Cached CSS for each tag
+            /// </summary>
             public List<TagInstanceCSSInfo> TagInstanceCSS = new();
         }
 
@@ -35 +66 @@
         private Dictionary<HtmlNode, HtmlNode> NodeDict = new();
         private List<TagInstanceCSSInfo> TagInstanceCSS = new();
 
+        /// <summary>
+        /// Unpack cached info into local (request-scoped) variables
+        /// </summary>
+        /// <param name="cachedInfo"></param>
         private void UnpackCachedInfo(CachedInfo cachedInfo)
         {
             TagStartPositions = cachedInfo.TagStartPositions;
@@ -62 +97 @@
 
             int currentId = 0;
 
+            // Create mapping original-document-node -> to-edit-document-node
             FillNodeDict(descendantsOriginal, descendantsToEdit);
+
+            // Assign IDs to all original rtags
             AssignIdsToOriginalDocument(descendantsOriginal, ref currentId);
 
+            // Wrap all text that is not in a tag or where the parent node contains tags as children also in spans
             WrapTextInSpan(descendantsOriginal, docToEdit);
 
             descendantsToEdit = docToEdit.DocumentNode.DescendantsAndSelf().ToList();
@@ -156 +195 @@
             });
         }
 
+        /// <summary>
+        /// Wrap text in span when the target text is the whole text of the target tag
+        /// </summary>
+        /// <param name="node">text node to wrap</param>
+        /// <param name="selectionStart">start of the selection in the edited document</param>
+        /// <param name="selectionEnd">end of the selection in the edited document</param>
+        /// <param name="start">start of the node</param>
+        /// <param name="end">end of the node</param>
+        /// <param name="docToEdit">document to edit</param>
+        /// <param name="tag">tag we are adding</param>
+        /// <returns></returns>
         private HtmlNode SolveFullFill(HtmlNode node, int selectionStart, int selectionEnd, int start, int end, HtmlDocument docToEdit, AnnotationTagGeneric tag)
         {
             // full fill
@@ -185 +235 @@
             return spanSelected;
         }
 
+        /// <summary>
+        /// Wrap text in span when the target text starts at the start of the tag and leaves space on the right side
+        /// </summary>
+        /// <param name="node">text node to wrap</param>
+        /// <param name="selectionStart">start of the selection in the edited document</param>
+        /// <param name="selectionEnd">end of the selection in the edited document</param>
+        /// <param name="start">start of the node</param>
+        /// <param name="end">end of the node</param>
+        /// <param name="docToEdit">document to edit</param>
+        /// <param name="tag">tag we are adding</param>
+        /// <returns></returns>
         private List<HtmlNode> SolveRightGap(HtmlNode node, int selectionStart, int selectionEnd, int start, int end, HtmlDocument docToEdit,
                                              AnnotationTagGeneric tag)
         {
@@ -215 +276 @@
             return new() { spanSelected, spanAfter };
         }
 
+        /// <summary>
+        /// Wrap text in span when the target text ends at the end of the tag but leaves space on the left
+        /// </summary>
+        /// <param name="node">text node to wrap</param>
+        /// <param name="selectionStart">start of the selection in the edited document</param>
+        /// <param name="selectionEnd">end of the selection in the edited document</param>
+        /// <param name="start">start of the node</param>
+        /// <param name="end">end of the node</param>
+        /// <param name="docToEdit">document to edit</param>
+        /// <param name="tag">tag we are adding</param>
+        /// <returns></returns>
         private List<HtmlNode> SolveLeftGap(HtmlNode node, int selectionStart, int selectionEnd, int start, int end, HtmlDocument docToEdit,
                                              AnnotationTagGeneric tag)
         {
@@ -245 +317 @@
             return new() { spanSelected, spanBefore };
         }
 
+        /// <summary>
+        /// Wrap text in span when the target text is contained in the node but neither starts or ends match
+        /// </summary>
+        /// <param name="node">text node to wrap</param>
+        /// <param name="selectionStart">start of the selection in the edited document</param>
+        /// <param name="selectionEnd">end of the selection in the edited document</param>
+        /// <param name="start">start of the node</param>
+        /// <param name="end">end of the node</param>
+        /// <param name="docToEdit">document to edit</param>
+        /// <param name="tag">tag we are adding</param>
+        /// <returns></returns>
         private List<HtmlNode> SolveLeftRightGap(HtmlNode node, int selectionStart, int selectionEnd, int start, int end, HtmlDocument docToEdit,
                                                  AnnotationTagGeneric tag)
         {
@@ -274 +357 @@
             return new() { spanSelected, spanBefore, spanAfter };
         }
 
+        /// <summary>
+        /// Create span utility method
+        /// </summary>
+        /// <param name="doc">document</param>
+        /// <param name="text">inner text of the span</param>
+        /// <param name="tagId">ID of the tag (TAG_ID_ATTRIBUTE_NAME)</param>
+        /// <param name="instanceId">ID of the instance (TAG_INSTANCE_ATTRIBUTE_NAME)</param>
+        /// <param name="entityId">Id of the EF entity (TAG_EF_ID_NAME)</param>
+        /// <param name="startPosition"></param>
+        /// <param name="position"></param>
+        /// <returns></returns>
         private HtmlNode CreateSpan(HtmlDocument doc, string text, int tagId, Guid? instanceId, Guid? entityId, int startPosition, EPosition position = EPosition.MARK_NONE)
         {
             HtmlNode span = doc.CreateElement("span");
@@ -312 +406 @@
             MARK_NONE = 0
         }
 
+        /// <summary>
+        /// Redirect all links
+        /// </summary>
+        /// <param name="descendantsOriginal"></param>
         private void ModifyLinks(IEnumerable<HtmlNode> descendantsOriginal)
         {
             foreach (var descendant in descendantsOriginal)
@@ -327 +425 @@
             }
         }
 
+        /// <summary>
+        /// Wrap all #text nodes in spans
+        /// </summary>
+        /// <param name="descendantsOriginal"></param>
+        /// <param name="docToEdit"></param>
         private void WrapTextInSpan(IEnumerable<HtmlNode> descendantsOriginal, HtmlDocument docToEdit)
         {
             // Special case for non-html documents
@@ -389 +492 @@
                         foreach (var child in node.ChildNodes)
                         {
                             if (child.Name.Contains("#text"))
-                            {
+                            { 
                                 HtmlNode coveringSpan = docToEdit.CreateElement("span");
                                 coveringSpan.InnerHtml = child.InnerHtml;
+                                
+                                // Add length of 0 - in they were not in the original document
                                 TagStartPositions.Add(child.InnerStartIndex);
                                 TagStartLengths.Add(0);
                                 TagClosingPositions.Add(child.InnerStartIndex + child.InnerLength);
@@ -410 +515 @@
             }
         }
 
+        /// <summary>
+        /// Generate CSS for all tag instances
+        /// </summary>
+        /// <param name="tags"></param>
         private void GenerateCSS(List<AnnotationTagGeneric> tags)
         {
             /*string inner = "span.annotation {border-bottom: 2px solid;}";
@@ -428 +537 @@
             }
         }
 
+        /// <summary>
+        /// Add IDs to all tags in the original document
+        /// </summary>
+        /// <param name="descendantsOriginal"></param>
+        /// <param name="currentId"></param>
         private void AssignIdsToOriginalDocument(IEnumerable<HtmlNode> descendantsOriginal, ref int currentId)
         {
             foreach (var node in descendantsOriginal)
@@ -446 +560 @@
                     currentId = TagStartPositions.Count - 1;
                     toEditNode.Attributes.Add(TAG_ID_ATTRIBUTE_NAME, currentId.ToString());
 
+                    // Cross-referencing of the original document to the edited document
                     TagClosingPositions.Add(originalNode.InnerStartIndex + originalNode.InnerLength);
                     TagClosingLengths.Add((originalNode.OuterStartIndex + originalNode.OuterLength) - (originalNode.InnerStartIndex + originalNode.InnerLength));
                 }
@@ -476 +591 @@
          *      Partial HTML Preprocessing ----------------------------------------------------------------------------
          */
 
+        /// <summary>
+        /// Incrementally modifies the html to render and cached info by adding a new tag
+        /// </summary>
+        /// <param name="htmlToEdit"></param>
+        /// <param name="htmlOriginal"></param>
+        /// <param name="tagToAdd"></param>
+        /// <param name="tags"></param>
+        /// <param name="cachedInfo"></param>
+        /// <returns></returns>
         public (string, CachedInfo) PartialPreprocessHTMLAddTag(string htmlToEdit, string htmlOriginal, AnnotationTagGeneric tagToAdd, List<AnnotationTagGeneric> tags, CachedInfo cachedInfo)
         {
             UnpackCachedInfo(cachedInfo);
@@ -547 +671 @@
             });
         }
 
-
+        /// <summary>
+        /// Removing tag effectively just cleans up the attributes and CSS thus has no effect
+        /// </summary>
+        /// <param name="htmlToEdit"></param>
+        /// <param name="htmlOriginal"></param>
+        /// <param name="tagToRemove"></param>
+        /// <param name="tags"></param>
+        /// <param name="cachedInfo"></param>
+        /// <returns></returns>
         public (string, CachedInfo) PartialPreprocessHTMLRemoveTag(string htmlToEdit, string htmlOriginal, AnnotationTagGeneric tagToRemove, List<AnnotationTagGeneric> tags, CachedInfo cachedInfo)
         {
             UnpackCachedInfo(cachedInfo);