Revize a35cb648

Added comments to backend

Backend/Backend/Authentication/AuthorizationAttribute.cs

@@ -6 +6 @@
 
 namespace RestAPI.Authentication;
 
+/// <summary>
+/// Authorization attribute for endpoints and controllers
+/// By default minimum role is ANNOTATOR
+/// Access is granted to any role with same or higher privilege than the specified one (or default, if none is specified)
+/// </summary>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
 public class AuthorizeAttribute : Attribute, IAuthorizationFilter
 {

Backend/Backend/Controllers/AnnotationController.cs

@@ -10 +10 @@
 using Models.Tags;
 using Core.Services.TagService;
 
-
+/// <summary>
+/// /annotation* endpoint controller
+/// </summary>
 namespace RestAPI.Controllers
 {
     public class AnnotationController : CommonControllerBase

Backend/Backend/Controllers/AuthController.cs

@@ -10 +10 @@
 
 namespace RestAPI.Controllers;
 
+/// <summary>
+/// Authentication controller
+/// </summary>
 public class AuthController : CommonControllerBase
 {
     private readonly IAuthService authService;
@@ -48 +51 @@
         }
     }
 
+    /// <summary>
+    /// Test only
+    /// </summary>
+    /// <param name="clientInfo"></param>
+    /// <returns></returns>
     [HttpGet("/auth/test")]
     [ProducesResponseType((int) HttpStatusCode.OK, Type = typeof(ClientInfo))]
     [ProducesResponseType((int) HttpStatusCode.Forbidden)]
@@ -56 +64 @@
         return clientInfo;
     }
     
-    
+    /// <summary>
+    /// Test only
+    /// </summary>
+    /// <param name="clientInfo"></param>
+    /// <returns></returns>
     [AllowAnonymous]
     [HttpGet("/auth/test/aa")]
     [ProducesResponseType((int) HttpStatusCode.OK, Type = typeof(ClientInfo))]

Backend/Backend/Controllers/Common/CommonControllerBase.cs

@@ -4 +4 @@
 
 namespace RestAPI.Controllers.Common;
 
+/// <summary>
+/// Base controller with universal headers
+/// Note that by default endpoints are [Authorize], so if an endpoint should not be logged-user-only, add [AllowAnonymous]
+/// </summary>
 [ApiController]
 [Authorize]
 [ProducesResponseType((int)HttpStatusCode.InternalServerError)]

Backend/Backend/Controllers/DocumentController.cs

@@ -15 +15 @@
 namespace RestAPI.Controllers;
 
 
-
+/// <summary>
+/// /document* endpoint controller
+/// </summary>
 public class DocumentController : Common.CommonControllerBase
 {
     private readonly IDocumentService documentService;

Backend/Backend/Controllers/TagController.cs

@@ -13 +13 @@
 namespace RestAPI.Controllers;
 
 
-
+/// <summary>
+/// /tag* endpoint controller
+/// </summary>
 public class TagController : Common.CommonControllerBase
 {
     private readonly ITagService tagService;
     private readonly ILogger logger;
 
-
     public TagController(ITagService tagService, ILogger logger)
     {
         this.tagService = tagService;

Backend/Backend/Controllers/UserController.cs

@@ -11 +11 @@
 
 namespace RestAPI.Controllers
 {
+    /// <summary>
+    /// /user* endpoint controller
+    /// </summary>
     public class UserController : CommonControllerBase
     {
         private readonly Serilog.ILogger logger;

Backend/Backend/Exceptions/BadRequestException.cs

@@ -6 +6 @@
 
 namespace RestAPI.Exceptions
 {
+    /// <summary>
+    /// Exception raised when there is a problem with client's request
+    /// Catched by error handling middleware
+    /// </summary>
     public class BadRequestException : Exception
     {
         public BadRequestException() { }

Backend/Backend/Exceptions/InternalErrorException.cs

@@ -6 +6 @@
 
 namespace RestAPI.Exceptions
 {
+    /// <summary>
+    /// Exception raised when there is an internal server error
+    /// Catched by error handling middleware
+    /// </summary>
     public class InternalErrorException : Exception
     {
         public InternalErrorException() { }

Backend/Backend/Middleware/ErrorMiddleware.cs

@@ -4 +4 @@
 
 namespace RestAPI.Middleware
 {
+    /// <summary>
+    /// Middleware for global error handling
+    /// </summary>
     public class ErrorMiddleware
     {
         private readonly RequestDelegate _next;

Backend/Backend/Program.cs

@@ -76 +76 @@
     app.UseSwaggerUI();
 }
 
-//app.UseHttpsRedirection();
-
 // CORS
 app.UseCors(builder => builder
                 .AllowAnyHeader()

Backend/Backend/Utils/ClientInfo.cs

@@ -2 +2 @@
 
 namespace RestAPI.Utils;
 
+/// <summary>
+/// Request client information
+/// </summary>
 public class ClientInfo
 {
     public bool IsLogged => LoggedUser != null;
-
     public User? LoggedUser { get; set; } = null;
-
     public string IP { get; set; } = "unknown";
 }

Backend/Backend/Utils/ContextUtils.cs

@@ -18 +18 @@
         }
     }
 
+    /// <summary>
+    /// Exctracts client information given HttpContext
+    /// </summary>
+    /// <param name="context"></param>
+    /// <returns></returns>
     public static ClientInfo GetClientInfo(HttpContext? context)
     {
         var ci = new ClientInfo();

Backend/Core/Authentication/JwtUtils.cs

@@ -16 +16 @@
 
 public class JwtUtils : IJwtUtils
 {
-    private const int EXPIRATION_SECONDS = 8 * 60 * 60; // 8 hod
+    private const int EXPIRATION_SECONDS = 8 * 60 * 60; // 8 hrs
 
     private readonly JwtConfig _jwtConfig;
     private readonly TokenValidationParameters _tokenValidationParameters;

Backend/Core/Constants/Constants.cs

@@ -8 +8 @@
 {
     public class Constants
     {
+        /// <summary>
+        /// Key for RequiredAnnotation value in database
+        /// </summary>
         public static string RequiredAnnotationsKey { get; } = "RequiredAnnotations"; 
     }
 }

Backend/Core/Contexts/DatabaseContext.cs

@@ -35 +35 @@
         protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
         {
             optionsBuilder.UseNpgsql(_configuration["ConnectionString"], b => b.MigrationsAssembly("RestAPI"));
-            //optionsBuilder.UseNpgsql("Host=localhost:5432;Database=dbo;Username=myuser;Password=password");
-        }
-
-        protected override void OnModelCreating(ModelBuilder modelBuilder)
-        {
         }
     }
 }

Backend/Core/Entities/Annotation.cs

@@ -11 +11 @@
 {
     public class Annotation : BaseEntity
     {
-        /*[ForeignKey("Document")]
-        public int DocumentId { get; set; }*/
+        /// <summary>
+        /// Document that the annotation refers to
+        /// </summary>
         public Document Document { get; set; }
         
-        /*[ForeignKey("User")]
-        public int UserId { get; set; }*/
+        /// <summary>
+        /// User the annotation is assigned to
+        /// </summary>
         public User User { get; set; }
 
-        /*[ForeignKey("User")]
-        public int UserAssignedId { get; set; }*/
+        /// <summary>
+        /// The user that assigned the annotation
+        /// </summary>
         public User UserAssigned { get; set; }
 
+        /// <summary>
+        /// The date the annotation was assigned
+        /// </summary>
         public DateTime DateAssigned { get; set; }
+        
+        /// <summary>
+        /// The state of the annotation
+        /// </summary>
         public EState State { get; set; }
+
+        /// <summary>
+        /// The date the annotation was last modified
+        /// </summary>
         public DateTime DateLastChanged { get; set; }
+
+        /// <summary>
+        /// Annotation note
+        /// </summary>
         public string Note { get; set; } = "";
 
+        //Cached information START
         public string CachedDocumentHTML { get; set; } = "";
         public string CachedStartPositions { get; set; } = "";
         public string CachedLengths { get; set; } = "";
         public string CachedClosingPositions { get; set; } = "";
         public string CachedClosingLengths { get; set; } = "";
         public string CachedCSS { get; set; } = "";
+        //Cached information END 
 
+        /// <summary>
+        /// ID of the last modified tag
+        /// </summary>
         public Guid? LastModifiedTagId { get; set; }
+
+        /// <summary>
+        /// The modification that is done
+        /// </summary>
         public EModified ModifiedType { get; set; } = EModified.NONE;
 
+        /// <summary>
+        /// Unused
+        /// </summary>
         public ICollection<Class> Classes { get; set; } = new List<Class>();
 
+        /// <summary>
+        /// So that EF creates a join table as 1 final annotation to N annotations
+        /// </summary>
+
         public ICollection<FinalAnnotation> FinalAnnotations { get; set; } = new List<FinalAnnotation>();
     }
 }

Backend/Core/Entities/AnnotationTag.cs

@@ -11 +11 @@
 {
     public class AnnotationTag : AnnotationTagGeneric
     {
+        /// <summary>
+        /// The annotation the annotation tag is linked to
+        /// </summary>
         public Annotation Annotation { get; set; }
     }
 }

Backend/Core/Entities/AnnotationTagGeneric.cs

@@ -7 +7 @@
 
 namespace Core.Entities
 {
+    /// <summary>
+    /// Base class for tag occurences in annotations
+    /// </summary>
     public class AnnotationTagGeneric : BaseEntity
     {
+        /// <summary>
+        /// Tag
+        /// </summary>
         public Tag Tag { get; set; }
 
-        /** Nullable for optional */
+        /// <summary>
+        /// Subtag, nulllable for optional
+        /// </summary>
         public SubTag? SubTag { get; set; }
 
+        /// <summary>
+        /// Id of the instance (shared by multipart tags)
+        /// </summary>
         public Guid Instance { get; set; }
+
+        /// <summary>
+        /// The tag note
+        /// </summary>
         public string Note { get; set; }
         public int Position { get; set; }
         public int Length { get; set; }
+
+        /// <summary>
+        /// Sentiment of the tag, nullable for optional
+        /// </summary>
         public ETagSentiment? Sentiment { get; set; }
+        
+        /// <summary>
+        /// The text that the tag is covering
+        /// </summary>
         public string SelectedText { get; set; }
     }
 }

Backend/Core/Entities/BaseEntity.cs

@@ -7 +7 @@
 
 namespace Core.Entities
 {
+    /// <summary>
+    /// Base entity, defines the ID
+    /// </summary>
     public class BaseEntity
     {
        [Key]

Backend/Core/Entities/Class.cs

@@ -7 +7 @@
 
 namespace Core.Entities
 {
+    /// <summary>
+    /// Unused
+    /// </summary>
     public class Class : BaseEntity
     {
         public string Name { get; set; }

Backend/Core/Entities/ConfigurationItem.cs

@@ -6 +6 @@
 
 namespace Core.Entities
 {
+    /// <summary>
+    /// Configuration for the key-value database storage
+    /// </summary>
     public class ConfigurationItem : BaseEntity
     {
         public string Value { get; set; }

Backend/Core/Entities/Document.cs

@@ -11 +11 @@
 #nullable disable
     public class Document : BaseEntity
     {
+        /// <summary>
+        /// Document name
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// Length in characters
+        /// </summary>
         public int Length { get; set; }
 
+        /// <summary>
+        /// Actual content
+        /// </summary>
         public DocumentContent Content { get; set; }
 
+        /// <summary>
+        /// Date added
+        /// </summary>
         public DateTime DateAdded { get; set; }
 
+        /// <summary>
+        /// User who added it
+        /// </summary>
         public User UserAdded { get; set; }
 
+        /// <summary>
+        /// Number of required annotations
+        /// </summary>
         public int RequiredAnnotations { get; set; }
     }
 }

Backend/Core/Entities/DocumentContent.cs

@@ -10 +10 @@
 {
     public class DocumentContent : BaseEntity
     {
+        /// <summary>
+        /// String with the document content
+        /// </summary>
         public string Content { get; set; }
     }
 }

Backend/Core/Entities/FinalAnnotation.cs

@@ -9 +9 @@
 {
     public class FinalAnnotation : Annotation
     {
+        /// <summary>
+        /// List of annotations that were used to create the final annotation
+        /// </summary>
         public List<Annotation> Annotations { get; set; } = new();
     }
 }

Backend/Core/Entities/FinalAnnotationTag.cs

@@ -8 +8 @@
 {
     public class FinalAnnotationTag : AnnotationTagGeneric
     {
+        /// <summary>
+        /// FinalAnnotation the tag is linked to
+        /// </summary>
         public FinalAnnotation Annotation { get; set; }
+
+        /// <summary>
+        /// Whether the tag is marked as final or not
+        /// </summary>
         public bool IsFinal { get; set; } = false;
+        
+        /// <summary>
+        /// List of users who have agreed on this tag
+        /// </summary>
         public ICollection<User> Users { get; set; } = new List<User>();
     }
 }

Backend/Core/Entities/SubTag.cs

@@ -12 +12 @@
         public string Name { get; set; }
         public string Description { get; set; }
         public Tag Tag { get; set; }
+
+        /// <summary>
+        /// Whether or not this tag supports sentiment
+        /// </summary>
         public bool SentimentEnabled { get; set; } = false;
     }
 }

Backend/Core/Entities/Tag.cs

@@ -14 +14 @@
         public string Name { get; set; }
         public string Description { get; set; }
         public string Color { get; set; }
+
+        /// <summary>
+        /// Whether or not this tag supports sentiment
+        /// </summary>
         public bool SentimentEnabled { get; set; } = false;
     }
 }

Backend/Core/Entities/TagCategory.cs

@@ -13 +13 @@
         public string Name { get; set; }
         public string Color { get; set; }
         public string Description { get; set; }
+
+        /// <summary>
+        /// Whether or not this category is only visible to admins
+        /// </summary>
         public bool DisabledForAnnotators { get; set; } = false;
     }
 }

Backend/Core/Entities/User.cs

@@ -21 +21 @@
 
         public ERole Role { get; set; }
 
+        /// <summary>
+        /// Force EF to create a join table
+        /// </summary>
         public ICollection<FinalAnnotationTag> FinalAnnotationTags { get; set; } = new List<FinalAnnotationTag>();
     }
 }

Backend/Core/GraphUtils/Intersections.cs

@@ -4 +4 @@
 {
     public class Intersections
     {
+        /// <summary>
+        /// Finds intersections between 1D segments
+        /// </summary>
+        /// <param name="tags"></param>
+        /// <returns></returns>
         public static Dictionary<AnnotationTagGeneric, List<AnnotationTagGeneric>> FindIntersections(List<AnnotationTagGeneric> tags)
         {
             var intersections = new Dictionary<AnnotationTagGeneric, List<AnnotationTagGeneric>>();
@@ -27 +32 @@
             return intersections;
         }
 
+        /// <summary>
+        /// Graph coloring
+        /// </summary>
+        /// <param name="source"></param>
+        /// <returns></returns>
         public static Dictionary<AnnotationTagGeneric, int> ColorGraph(Dictionary<AnnotationTagGeneric, List<AnnotationTagGeneric>> source)
         {
             var res = ConvertToMatrix(source);

Backend/Core/MapperProfiles/DocumentProfileEF.cs

@@ -14 +14 @@
         public DocumentProfileEF()
         {
             CreateMap<Document, DocumentListInfo>();
-                /*.ForMember(dest => dest.Id, opt => opt.MapFrom(src => src.Id))
-                .ForMember(dest => dest.Name, opt => opt.MapFrom(src => src.Name))
-                .ForMember(dest => dest.Length, opt => opt.MapFrom(src => src.Length))
-                .ForMember(dest => dest.RequiredAnnotations, opt => opt.MapFrom(src => src.RequiredAnnotations));*/
-
         }
     }
 }

Backend/Core/MapperProfiles/RegisterMappings.cs

@@ -11 +11 @@
 {
     public class RegisterMappings
     {
+        /// <summary>
+        /// Registers mappings for AutoMapper in DI
+        /// </summary>
+        /// <param name="builder"></param>
         public static void Register(WebApplicationBuilder builder)
         {
-            builder.Services.AddAutoMapper(typeof(UserProfileEF), typeof(DocumentProfileEF));
+            builder.Services.AddAutoMapper(typeof(UserProfileEF), typeof(DocumentProfileEF), typeof(TagProfileEF));
         }
     }
 }

Backend/Core/Services/AnnotationService/IAnnotationService.cs

@@ -11 +11 @@
 {
     public interface IAnnotationService
     {
+        /// <summary>
+        /// Assign users to documents
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="userId"></param>
         public void CreateDocumentAnnotations(AnnotationsAddRequest request, Guid userId);
+        /// <summary>
+        /// Given user, return their annotations
+        /// </summary>
+        /// <param name="userId"></param>
+        /// <returns></returns>
         public AnnotationListResponse GetUserAnnotations(Guid userId);
+        /// <summary>
+        /// Return given annotation
+        /// </summary>
+        /// <param name="annotationId"></param>
+        /// <param name="userId"></param>
+        /// <param name="userRole"></param>
+        /// <param name="isFinal">is it final annotation or standard annotation</param>
+        /// <returns></returns>
         public AnnotationInfo GetAnnotation(Guid annotationId, Guid userId, ERole userRole, bool isFinal);
+        /// <summary>
+        /// Adds a tag to an annotation
+        /// </summary>
+        /// <param name="annotationId"></param>
+        /// <param name="userId"></param>
+        /// <param name="userRole"></param>
+        /// <param name="request"></param>
+        /// <param name="isFinal">is it final annotation or standard annotation</param>
         public void AddAnnotationInstance(Guid annotationId, Guid userId, ERole userRole, AnnotationInstanceAddRequest request, bool isFinal);
+        /// <summary>
+        /// Remove a tag from annotation
+        /// </summary>
+        /// <param name="annotationId"></param>
+        /// <param name="tagInstanceId"></param>
+        /// <param name="loggedUserId"></param>
+        /// <param name="userRole"></param>
+        /// <param name="isFinal">is it final annotation or standard annotation</param>
         public void DeleteAnnotationInstance(Guid annotationId, Guid tagInstanceId, Guid loggedUserId, ERole userRole, bool isFinal);
+        /// <summary>
+        /// Add note to annotation
+        /// </summary>
+        /// <param name="annotationId"></param>
+        /// <param name="userId"></param>
+        /// <param name="userRole"></param>
+        /// <param name="request"></param>
+        /// <param name="isFinal">is it final annotation or standard annotation</param>
         public void AddNoteToAnnotation(Guid annotationId, Guid userId, ERole userRole, AddNoteToAnnotationRequest request, bool isFinal);
+        /// <summary>
+        /// Set sentiment of a tag
+        /// </summary>
+        /// <param name="annotationId"></param>
+        /// <param name="instanceId"></param>
+        /// <param name="userId"></param>
+        /// <param name="userRole"></param>
+        /// <param name="sentiment"></param>
+        /// <param name="isFinal">is it final annotation or standard annotation</param>
         public void SetTagInstanceSentiment(Guid annotationId, Guid instanceId, Guid userId, ERole userRole, ETagSentiment sentiment, bool isFinal);
+        /// <summary>
+        /// Set the annotation state to DONE or IN_PROGRESS
+        /// </summary>
+        /// <param name="annotationId"></param>
+        /// <param name="userId"></param>
+        /// <param name="userRole"></param>
+        /// <param name="done">is it DONE or not</param>
+        /// <param name="isFinal"is it final annotation or standard annotation></param>
         public void MarkAnnotationAsDone(Guid annotationId, Guid userId, ERole userRole, bool done, bool isFinal);
+        /// <summary>
+        /// Creates a final annotation
+        /// </summary>
+        /// <param name="documentId"></param>
+        /// <param name="userId"></param>
+        /// <returns>ID of the final annotation</returns>
         public Guid CreateFinalAnnotation(Guid documentId, Guid userId);
+        /// <summary>
+        /// Performs an export
+        /// </summary>
+        /// <param name="request"></param>
+        /// <returns>ZIP memory stream</returns>
         public MemoryStream Export(ExportRequest request);
+        /// <summary>
+        /// Marks tag as final 
+        /// </summary>
+        /// <param name="annotationId"></param>
+        /// <param name="occurenceId"></param>
+        /// <param name="isFinal">is the tag final or not</param>
         public void SetTagIsFinal(Guid annotationId, Guid occurenceId, bool isFinal);
     }
 }

Backend/Core/Services/AuthService/IAuthService.cs

@@ -5 +5 @@
 
 public interface IAuthService
 {
+    /// <summary>
+    /// Check username and password
+    /// </summary>
+    /// <param name="username"></param>
+    /// <param name="password"></param>
+    /// <returns></returns>
     public LoginResponse? Login(string username, string password);
 }

Backend/Core/Services/DocumentService/DocumentServiceEF.cs

@@ -63 +63 @@
         }
 
         /// <summary>
-        /// 
+        /// Process a zip file and returns a list of names and documents
         /// </summary>
         /// <param name="base64encoded"></param>
         /// <returns></returns>
@@ -91 +91 @@
             return (names, contents);
         }
 
+        /// <summary>
+        /// Save a document in the database
+        /// </summary>
+        /// <param name="content"></param>
+        /// <param name="userAdded"></param>
+        /// <param name="documentName"></param>
+        /// <param name="requiredAnnotations"></param>
         private void SaveDocument(string content, User userAdded, string documentName, int requiredAnnotations)
         {
             DocumentContent documentContent = new DocumentContent()
@@ -140 +147 @@
                 }
 
                 DocumentListInfo dli = mapper.Map<DocumentListInfo>(document);
+                // Add list of users taht annotate the document
                 dli.AnnotatingUsers = annotatingUsersDto;
 
+                // Add info about the finalized version
                 dli.FinalizedExists = databaseContext.FinalAnnotations.Any(fa => fa.Document == document);
                 if (dli.FinalizedExists)
                 {
@@ -154 +163 @@
                     dli.FinalizedState = finalizedAnnotation.State;
                     dli.FinalAnnotations = new();
 
+                    // Add information about which annotations were used to create the finalized version
                     foreach (var annotation in finalizedAnnotation.Annotations)
                     {
                         dli.FinalAnnotations.Add(new()

Backend/Core/Services/DocumentService/IDocumentService.cs

@@ -11 +11 @@
 {
     public interface IDocumentService
     {
+        /// <summary>
+        /// Add list of documents to a list of users
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="userId"></param>
         public void AddDocuments(DocumentAddRequest request, Guid userId);
+        /// <summary>
+        /// Returns all documents
+        /// </summary>
+        /// <returns></returns>
         public DocumentListResponse GetDocuments();
+        /// <summary>
+        /// Returns a preview of a document (HTML)
+        /// </summary>
+        /// <param name="documentId"></param>
+        /// <returns></returns>
         public DocumentPreviewResponse GetDocumentPreview(Guid documentId);
+        /// <summary>
+        /// Delete a list of documents
+        /// </summary>
+        /// <param name="request"></param>
         public void DeleteDocuments(DeleteDocumentsRequest request);
+        /// <summary>
+        /// Set required number of annotations for a list of documents
+        /// </summary>
+        /// <param name="request"></param>
         public void SetRequiredAnnotationsForDocuments(SetRequiredAnnotationsRequest request);
+        /// <summary>
+        /// Set default required number of annotations
+        /// </summary>
+        /// <param name="requiredAnnotations"></param>
         public void SetRequiredAnnotationsGlobal(int requiredAnnotations);
+        /// <summary>
+        /// Get default required number of annotations
+        /// </summary>
+        /// <returns></returns>
         public int GetRequiredAnnotationsGlobal();
+        /// <summary>
+        /// Remove an annotator from a document
+        /// </summary>
+        /// <param name="documentId"></param>
+        /// <param name="annotatorId"></param>
         public void RemoveAnnotatorFromDocument(Guid documentId, Guid annotatorId);
     }
 }

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);

Backend/Core/Services/HTMLService/IHTMLService.cs

@@ -10 +10 @@
 {
     public interface IHTMLService
     {
+        /// <summary>
+        /// Make a full preprocessing of an HTML document and incorporate any existing tags into it
+        /// </summary>
+        /// <param name="htmlSource"></param>
+        /// <param name="tags"></param>
+        /// <returns>tuple of (HTML document to render, info to cache in the database)</returns>
         public (string, CachedInfo) FullPreprocessHTML(string htmlSource, List<AnnotationTagGeneric> tags);
+        /// <summary>
+        /// Make a partial preprocessing of an HTML document by adding a new tag into it
+        /// </summary>
+        /// <param name="htmlToEdit">already preprocessed HTML document</param>
+        /// <param name="htmlOriginal">original HTML document</param>
+        /// <param name="tagToAdd">the tag to add</param>
+        /// <param name="tags">list of all tags related to the annotation</param>
+        /// <param name="cachedInfo">database-cached info</param>
+        /// <returns></returns>
         public (string, CachedInfo) PartialPreprocessHTMLAddTag(string htmlToEdit, string htmlOriginal, AnnotationTagGeneric tagToAdd, List<AnnotationTagGeneric> tags, CachedInfo cachedInfo);
+        /// <summary>
+        /// Make a partial preprocessing of an HTML document by remove an existing tag from it
+        /// </summary>
+        /// <param name="htmlToEdit">already preprocessed HTML document</param>
+        /// <param name="htmlOriginal">original HTML document</param>
+        /// <param name="tagToRemove">the tag to remove</param>
+        /// <param name="tags">list of all tags related to the annotation</param>
+        /// <param name="cachedInfo">database-cached info</param>
+        /// <returns></returns>
         public (string, CachedInfo) PartialPreprocessHTMLRemoveTag(string htmlToEdit, string htmlOriginal, AnnotationTagGeneric tagToRemove, List<AnnotationTagGeneric> tags, CachedInfo cachedInfo);
     }
 }

Backend/Core/Services/Registration.cs

@@ -7 +7 @@
 
 namespace Core.Services
 {
+    /// <summary>
+    /// Add new services here
+    /// </summary>
     public class Registration
     {
+        /// <summary>
+        /// Registers services
+        /// </summary>
+        /// <param name="builder"></param>
         public static void RegisterServices(WebApplicationBuilder builder)
         {
             builder.Services.AddScoped<IUserService, UserServiceEF>();

Backend/Core/Services/TagService/ITagService.cs

@@ -12 +12 @@
 {
     public interface ITagService
     {
+        /// <summary>
+        /// Returns a tree-like structure with tag categories, tags, and subtags
+        /// </summary>
+        /// <param name="userRole">Role is used to discriminate categories available to admins only</param>
+        /// <returns></returns>
         public TagTreeResponse GetTagTree(ERole userRole);
+        /// <summary>
+        /// Creates a new category
+        /// </summary>
+        /// <param name="request"></param>
         public void CreateCategory(CreateCategoryRequest request);
+        /// <summary>
+        /// Deleted a category by Id
+        /// </summary>
+        /// <param name="categoryId"></param>
         public void DeleteCategory(Guid categoryId);
+        /// <summary>
+        /// Updates a category by Id
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="categoryId"></param>
         public void UpdateCategory(ModifyCategoryRequest request, Guid categoryId);
+        /// <summary>
+        /// Creates a new tag
+        /// </summary>
+        /// <param name="request"></param>
         public void CreateTag(CreateTagRequest request);
+        /// <summary>
+        /// Delete tag by Id
+        /// </summary>
+        /// <param name="tagId"></param>
         public void DeleteTag(Guid tagId);
+        /// <summary>
+        /// Update tag by Id
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="tagId"></param>
         public void UpdateTag(ModifyTagRequest request, Guid tagId);
+        /// <summary>
+        /// Create a subtag
+        /// </summary>
+        /// <param name="request"></param>
         public void CreateSubTag(CreateSubTagRequest request);
+        /// <summary>
+        /// Delete subtag by Id
+        /// </summary>
+        /// <param name="subtagId"></param>
         public void DeleteSubTag(Guid subtagId);
+        /// <summary>
+        /// Update subtag by Id
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="subtagId"></param>
         public void UpdateSubTag(ModifySubTagRequest request, Guid subtagId);
+        /// <summary>
+        /// Adds a note to tag's instance
+        /// </summary>
+        /// <param name="annotationId">Annotation</param>
+        /// <param name="occurrenceId">Id of the Tag</param>
+        /// <param name="user">User that's doing the adding</param>
+        /// <param name="request"></param>
+        /// <param name="isFinal">Whether the annotationId is for a FinalAnnotation or Annotation</param>
         public void AddNoteToTagInstance(Guid annotationId, Guid occurrenceId, User user, AddNoteToTagOccurenceRequest request, bool isFinal);
     }
 }

Backend/Core/Services/TagService/TagServiceEF.cs

@@ -274 +274 @@
 
         public void AddNoteToTagInstance(Guid annotationId, Guid occurrenceId, User user, AddNoteToTagOccurenceRequest request, bool isFinal)
         {
+            // We need to differentiate whether or not the annotation is final
             Annotation annotation = null;
             try
             {

Backend/Core/Services/UserService/IUserService.cs

@@ -11 +11 @@
 {
     public interface IUserService
     {
+        /// <summary>
+        /// Creates a new user
+        /// </summary>
+        /// <param name="username"></param>
+        /// <param name="name"></param>
+        /// <param name="surname"></param>
+        /// <param name="password"></param>
+        /// <param name="role"></param>
+        /// <returns></returns>
         public User? CreateUser(string username, string name, string surname, string password, ERole role);
+        /// <summary>
+        /// Returns a user with the specified username or null if no such user exists
+        /// </summary>
+        /// <param name="username"></param>
+        /// <returns></returns>
         public User? GetUserByUsername(string username);
+        /// <summary>
+        /// Returns a user with the specified Id or null if no such user exists
+        /// </summary>
+        /// <param name="id"></param>
+        /// <returns></returns>
         public User? GetUserById(Guid id);
+        /// <summary>
+        /// Updates information about the user
+        /// Pass null as a parameter if you dont want to update it
+        /// </summary>
+        /// <param name="user"></param>
+        /// <param name="username"></param>
+        /// <param name="name"></param>
+        /// <param name="surname"></param>
+        /// <param name="role"></param>
+        /// <returns></returns>
         public User UpdateUser(User user, string? username = null, string? name = null, string? surname = null, ERole? role = null);
+        /// <summary>
+        /// Updates information about the user
+        /// Pass null as a parameter if you dont want to update it
+        /// </summary>
+        /// <param name="user"></param>
+        /// <param name="username"></param>
+        /// <param name="name"></param>
+        /// <param name="surname"></param>
+        /// <param name="role"></param>
+        /// <returns></returns>
         public User? UpdateUser(Guid userId, string? username = null, string? name = null, string? surname = null, ERole? role = null);
+        /// <summary>
+        /// Sets a new password
+        /// </summary>
+        /// <param name="user"></param>
+        /// <param name="newPassword"></param>
+        /// <returns></returns>
         public User ChangePassword(User user, string newPassword);
+        /// <summary>
+        /// Sets a new password
+        /// </summary>
+        /// <param name="user"></param>
+        /// <param name="newPassword"></param>
+        /// <returns></returns>
         public User? ChangePassword(Guid userId, string newPassword);
+        /// <summary>
+        /// Check if the user with this username has this password
+        /// </summary>
+        /// <param name="username"></param>
+        /// <param name="password"></param>
+        /// <returns></returns>
         public User? CheckUsernamePassword(string username, string password);
+        /// <summary>
+        /// Returns list of all users
+        /// </summary>
+        /// <returns></returns>
         public UserList GetUsers();
+        /// <summary>
+        /// Deletes a user
+        /// </summary>
+        /// <param name="userId"></param>
         public void DeleteUser(Guid userId);
     }
 }

Backend/Core/Services/UserService/UserServiceEF.cs

@@ -16 +16 @@
 {
     public class UserServiceEF : IUserService
     {
+        // DI
+
         private readonly DatabaseContext _databaseContext;
         private readonly ILogger _logger;
         private readonly IMapper _mapper;

Backend/Core/ZipUtils/Export.cs

@@ -10 +10 @@
 
 namespace Core.ZipUtils
 {
+    /// <summary>
+    /// Static methods for database exporting
+    /// </summary>
     public class Export
     {
+        /// <summary>
+        /// Exports the specified annotations
+        /// </summary>
+        /// <param name="documents">list of documents to export</param>
+        /// <param name="documentAnnotations">document-annotations to export mapping</param>
+        /// <param name="documentFinalAnnotations">document-final annotations to export mapping</param>
+        /// <param name="annotationTags">annotation-annotation tags mapping</param>
+        /// <param name="finalAnnotationTags">final annotation-final annotation tags mapping</param>
+        /// <returns></returns>
         public static MemoryStream FullExport(List<Document> documents, Dictionary<Document, List<Annotation>> documentAnnotations, Dictionary<Document, FinalAnnotation> documentFinalAnnotations,
             Dictionary<Annotation, List<AnnotationTag>> annotationTags, Dictionary<FinalAnnotation, List<FinalAnnotationTag>> finalAnnotationTags)
         {
             MemoryStream ms = new MemoryStream();
+            // Set keepOpen to true so that Dispose() does not close the MemoryStream
             var archive = new ZipArchive(ms, ZipArchiveMode.Create, true);
 
             for (int docIndex = 0; docIndex < documents.Count; docIndex++)
@@ -37 +50 @@
                     CreateFile(documentDir + $"/annotation_{annotationIndex:00000}.json", annotationInfoJson, archive);
                 }
 
+                // Deal with final annotation if it exists
                 var finalAnnotation = documentFinalAnnotations[document];
                 if (finalAnnotation == null)
                 {
@@ -48 +62 @@
                 CreateFile(documentDir + "/final.json", finalAnnotationInfoJson, archive);
             }
 
+            // Dispose of archive to close the header
             archive.Dispose();
             ms.Position = 0;
             return ms;
         }
 
+        /// <summary>
+        /// Creates a file and writes to it
+        /// </summary>
+        /// <param name="path">path to file</param>
+        /// <param name="fileContent">string to write</param>
+        /// <param name="archive">archive to write it to</param>
         private static void CreateFile(string path, string fileContent, ZipArchive archive)
         {
             var entry = archive.CreateEntry(path);
@@ -61 +82 @@
             entryStream.Close();
         }
 
+        /// <summary>
+        /// Dumps a Document into JSON-serialized ExportDocumentInfo
+        /// </summary>
+        /// <param name="document">Document to serialize</param>
+        /// <returns>JSON-serialized ExportDocumentInfo</returns>
         private static string DumpDocument(Document document)
         {
             ExportDocumentInfo documentInfo = new();
@@ -71 +97 @@
             return JsonConvert.SerializeObject(documentInfo);
         }
 
+        /// <summary>
+        /// Dumps annotation into JSON-serialized ExportAnnotationInfo
+        /// </summary>
+        /// <param name="annotation">Annotation to dump</param>
+        /// <param name="tags">Tags related to the annotation</param>
+        /// <param name="documentId">Id of the document the annotation is related to</param>
+        /// <returns>JSON-serialized ExportAnnotationInfo</returns>
         private static string DumpAnnotation(Annotation annotation, List<AnnotationTagGeneric> tags, Guid documentId)
         {
             ExportAnnotationInfo annotationInfo = new();
@@ -108 +141 @@
 
     public class ExportDocumentInfo
     {
+        /// <summary>
+        /// Document name
+        /// </summary>
         public string Name { get; set; }
+        /// <summary>
+        /// Original document content
+        /// </summary>
         public string Content { get; set; }
+        /// <summary>
+        /// Id of the document
+        /// </summary>
         public Guid DocumentId { get; set; }
     }
 
     public class ExportAnnotationInfo
     {
+        /// <summary>