refactor annotations

pdf-generator/Controllers/EvaluationReportController.cs

@@ -18,7 +18,7 @@ namespace PDFGenerator.Controllers
         /// <summary>
         /// Say hello!
         /// </summary>
-        /// <returns></returns>
+        /// <returns>"Hello"</returns>
         [HttpGet("Hello")]
         public string Get()
         {
@@ -26,10 +26,10 @@ namespace PDFGenerator.Controllers
         }
 
         /// <summary>
-        /// Generates the PDF report.
+        /// Generates the PDF for an evaluation report.
         /// </summary>
         /// <param name="evaluationReport">Evaluation report for which the PDF should be rendered.</param>
-        /// <returns>the PDF document as byte array</returns>
+        /// <returns>PDF document as byte array</returns>
         [HttpPost("RenderReport")]
         [RequestSizeLimit(100000000)]
         public byte[] RenderReport([FromBody] PDFGenerator.Models.EvaluationReport evaluationReport)

pdf-generator/EvaluationReport/Appendix.cs

@@ -27,9 +27,9 @@ namespace PDFGenerator.EvaluationReport
         }
 
         /// <summary>
-        /// Includes custom uploads to the available attachments.
+        /// Includes custom uploads to attachments available.
         /// </summary>
-        /// <param name="customUploads">custom attachments to be added</param>
+        /// <param name="customUploads">Custom attachments to be added.</param>
         public void UpdateAppendix(Dictionary<string, byte[]> customUploads)
         {
             foreach (KeyValuePair<string, byte[]> item in customUploads)
@@ -72,7 +72,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds a single attachment to document.
         /// </summary>
-        /// <param name="item">the item composed of an attachment key and content</param>
+        /// <param name="item">The item composed of an attachment key and content.</param>
         private void AddAttachment(KeyValuePair<string, byte[]> item)
         {
             PdfReader attachment = new PdfReader(new MemoryStream(item.Value));
@@ -82,13 +82,13 @@ namespace PDFGenerator.EvaluationReport
             // avoiding the exception 'PdfReader not opened with owner password' from third party encrypted PDF uploads involves
             // manipulating both 'unethicalReading' and 'encrypted' flags from PdfReader
 
-            // in case the original author of the document defined permissions, then these permissions are ignored by setting 'unethicalReading' to true;
-            // this is not a problem, as setting such permissions has become obsolete, because since PDF became an ISO standard, 
+            // In case the original author of the document defined permissions these permissions are ignored by setting 'unethicalReading' to true.
+            // This is not a problem, as setting such permissions has become obsolete, since PDF became an ISO standard and
             // there is no longer a penalty for removing those permissions 
             // (refer to https://stackoverflow.com/questions/48064902/itext-7-pdfreader-is-not-opened-with-owner-password-error)
             attachment.SetUnethicalReading(true);
 
-            // mislead iText into thinking that the original PDF file was not encrypted
+            // Mislead iText into thinking that the original PDF file was not encrypted
             attachment.GetType()
                 .GetField("encrypted", BindingFlags.NonPublic | BindingFlags.Instance)
                 .SetValue(attachment, false);
@@ -103,7 +103,7 @@ namespace PDFGenerator.EvaluationReport
                 SetPageOrientation(Orientation.Landscape);
             }
 
-            // if attachment orientation is portrait, but destination pdf is not
+            // if attachment orientation is portrait but destination pdf is not
             else if ((attachmentPageSize.GetHeight() > attachmentPageSize.GetWidth()) && ((int)Math.Round(attachmentPageSize.GetHeight()) > pageSize.GetHeight()))
             {
                 SetPageOrientation(Orientation.Portrait);
@@ -120,8 +120,8 @@ namespace PDFGenerator.EvaluationReport
                 AddPageBreak();
             }
 
-            // table for inserting imported pages;
-            // true flag: avoid memory overhead problems from big imported files
+            // table for inserting imported pages
+            // true flag: Avoid memory overhead problems from big imported files
             Table table = new Table(1, true)
             .UseAllAvailableWidth()
             .SetDestination(item.Key);
@@ -151,12 +151,12 @@ namespace PDFGenerator.EvaluationReport
 
                 table.AddCell(cell);
 
-                // flush content of a single page to render part of the table: cell objects that were rendered
-                // are made available  to the garbage collector so that the memory used by those objects can be released
+                // flush content of a single page to render part of the table:
+                // memory used be rendered cell objects is made available to the garbage collector for release
                 table.Flush();
             }
 
-            // once added all the cells, this writes the remainder of the table that wasn't rendered yet
+            // once all the cells are added write the remainder of the table that was not rendered yet
             table.Complete();
 
             source.Close();

pdf-generator/EvaluationReport/BaseSection.cs

@@ -29,8 +29,7 @@ namespace PDFGenerator.EvaluationReport
             Bookmarks = bookmarks;
             TableOfContents = tableOfContents;
 
-            // get the root outline from the PdfDocument: false indicates that
-            // iText does not need to update the outlines
+            // get root outline from the PdfDocument: false indicates iText does not need to update the outlines.
             RootOutline = Document.GetPdfDocument().GetOutlines(false);
         }
 
@@ -42,7 +41,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Gets the current page.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>The current page.</returns>
         protected int GetCurrentPage()
         {
             return Document.GetPdfDocument().GetNumberOfPages();
@@ -51,7 +50,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Gets default page size. 
         /// </summary>
-        /// <returns></returns>
+        /// <returns>The default page size.</returns>
         protected PageSize GetPageSize()
         {
             return Document.GetPdfDocument().GetDefaultPageSize();
@@ -60,8 +59,8 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Resizes image to fit page size.
         /// </summary>
-        /// <param name="image">image to be resized</param>
-        /// <returns>the resized image</returns>
+        /// <param name="image">Image to be resized.</param>
+        /// <returns>The resized image.</returns>
         protected Image GetScaledImage(Image image)
         {
             PageSize pageSize = GetPageSize();
@@ -77,12 +76,13 @@ namespace PDFGenerator.EvaluationReport
         }
 
         /// <summary>
-        /// Adds upload files directly to the document if they are images; uploads consisting of PDF files are
-        /// added to the available custom uploads to be rendered as attachments in appendix and links are added to the document referring to them; 
-        /// if the custom uploads are neither PDF nor image files, then an exception is triggered.
+        /// Adds upload files directly to the document if they are images.
+        /// Uploads consisting of PDF files are added to the available custom uploads to be rendered as attachments in appendix
+        /// and links are added to the document referring to them instead.
+        /// If the custom uploads are neither PDF files nor image files an exception is thrown.
         /// </summary>
-        /// <param name="uploads">new custom uploads to be considered</param>
-        /// <param name="customUploads">already available custom uploads</param>
+        /// <param name="uploads">New custom uploads to be considered.</param>
+        /// <param name="customUploads">Already available custom uploads.</param>
         protected void AddCustomUploads(CustomUploads uploads, Dictionary<string, byte[]> customUploads)
         {
             if (uploads.Files == null)
@@ -99,7 +99,8 @@ namespace PDFGenerator.EvaluationReport
             bool imagesAvailable = false;
             foreach (KeyValuePair<string, byte[]> file in uploads.Files)
             {
-                // only accept files in image or PDF format, otherwise an exception is triggered below
+                // only accept files in image or PDF format, otherwise an exception is thrown below
+
                 // firstly, check if file is a valid image
                 if (ImageDataFactory.IsSupportedType(file.Value))
                 {
@@ -115,7 +116,7 @@ namespace PDFGenerator.EvaluationReport
                     continue;
                 }
 
-                // secondly, if data does not correspond to a PDF file, an exception is triggered
+                // secondly, if data does not correspond to a PDF file, an exception is thrown
                 new PdfReader(new MemoryStream(file.Value));
 
                 if (!customUploads.ContainsKey(file.Key))
@@ -145,10 +146,10 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds paragraph above the table.
         /// </summary>
-        /// <param name="table">the table, on which the paragraph is added</param>
-        /// <param name="text">the paragrah content</param>
-        /// <param name="header">flag indicatesm whether the content is a hedaer for the table</param>
-        /// <param name="style">given style for paragraph</param>
+        /// <param name="table">The table on which the paragraph is added.</param>
+        /// <param name="text">The paragraphs content.<param>
+        /// <param name="header">Flag indicating whether the content is a table header.</param>
+        /// <param name="style">Given style for paragraph.</param>
         protected void AddParagraphWithLeadingToTable(Table table, string text, bool header, Style style = null)
         {
             Cell cell = new Cell().SetBorder(Border.NO_BORDER);
@@ -173,7 +174,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Changes the page orientation.
         /// </summary>
-        /// <param name="orientation"></param>
+        /// <param name="orientation">Orientation to change to.</param>
         protected void SetPageOrientation(Orientation orientation)
         {
             if (orientation == Orientation.Landscape)
@@ -194,11 +195,11 @@ namespace PDFGenerator.EvaluationReport
         }
 
         /// <summary>
-        /// Prevents the default trim of existent leading whitespaces at the string beginning and immediately after a linebreak on iText7,
-        /// by adding a NULL character ('\u0000')
+        /// Prevents the default trim of leading whitespaces in the string
+        /// and immediately after a linebreak on iText7 by adding a NULL character ('\u0000')
         /// </summary>
-        /// <param name="text">input text</param>
-        /// <returns>text with preserved leading whitespaces</returns>
+        /// <param name="text">Text which leading whitespaces to be preserved.</param>
+        /// <returns>Text with preserved leading whitespaces.</returns>
         protected string PreserveLeadingSpaces(string text)
         {
             return "\u0000" + Regex.Replace(text, @"\n", "\n\u0000");
@@ -215,7 +216,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds scaled image to document.
         /// </summary>
-        /// <param name="image"></param>
+        /// <param name="image">Image to add do document.</param>
         private void AddScaledImage(Image image)
         {
             Document.Add(GetScaledImage(image));

pdf-generator/EvaluationReport/CourseGeneralInformation.cs

@@ -68,7 +68,7 @@ namespace PDFGenerator.EvaluationReport
                         AddCustomUploads(item.UploadedFilesForTopic, CustomUploads);
                     }
 
-                    // description for the current topic, if available (topic-dependent)
+                    // description for the current topic, if available (depends on topic)
                     if (item.Paragraphs.Count == 2)
                     {
                         Document.Add(ParagraphFactory.GetStandardParagraph(item.Paragraphs[1]));

pdf-generator/EvaluationReport/CourseInformationTables.cs

@@ -102,9 +102,9 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds a new cell to table.
         /// </summary>
-        /// <param name="table">the table, on which a new cell is added</param>
-        /// <param name="text">the cell content</param>
-        /// <param name="leftColumn">flag to differentiate between left and right column</param>
+        /// <param name="table">The table on which a new cell is added.</param>
+        /// <param name="text">The cell content.</param>
+        /// <param name="leftColumn">Flag to differentiate between left and right column.</param>
         private void AddCell(Table table, string text, bool leftColumn)
         {
             Cell cell = new Cell().Add(

pdf-generator/EvaluationReport/Cover.cs

@@ -31,7 +31,6 @@ namespace PDFGenerator.EvaluationReport
             Image image = new Image(imageData);
             PageSize pageSize = GetPageSize();
 
-            //TODO Noch nicht 100% Vorgaben corporate design
             image.ScaleAbsolute(MillimetersToPoints(60), MillimetersToPoints(16));
             image.SetFixedPosition(
                 pageSize.GetRight() - image.GetImageScaledWidth() - MillimetersToPoints(5),

pdf-generator/EvaluationReport/CriterionTarget.cs

@@ -78,7 +78,8 @@ namespace PDFGenerator.EvaluationReport
             {
                 if (Target.EvaluatedCriterions.Any(evaluatedCrit => !string.IsNullOrEmpty(evaluatedCrit.Description)))
                 {
-                    Document.Add(ParagraphFactory.GetCustomParagraph(Target.Paragraphs[count++], Styles.H4, 5f, 2f, 1.15f));        // zielsetzung
+                    // aimed target
+                    Document.Add(ParagraphFactory.GetCustomParagraph(Target.Paragraphs[count++], Styles.H4, 5f, 2f, 1.15f));
                 }
 
                 Target.EvaluatedCriterions.ForEach(item =>
@@ -90,14 +91,15 @@ namespace PDFGenerator.EvaluationReport
                             Document.Add(ParagraphFactory.GetCustomParagraph(item.CourseName, Styles.H5, 5f, 5f, 1.15f));
                         }
 
-                        // avoid that existent multiple white spaces immediately after a line break are ignored from iText7
+                        // avoid that existent multiple whitespaces after a line break are ignored by iText7
                         Document.Add(ParagraphFactory.GetStandardParagraph(PreserveLeadingSpaces(item.Description)));
                     }
                 });
 
                 if (Target.EvaluatedCriterions.Any(evaluatedCrit => !string.IsNullOrEmpty(evaluatedCrit.Comment)))
                 {
-                    Document.Add(ParagraphFactory.GetCustomParagraph(Target.Paragraphs[count++], Styles.H4, 5f, 2f, 1.15f));        // IST-Stand
+                    // actual state
+                    Document.Add(ParagraphFactory.GetCustomParagraph(Target.Paragraphs[count++], Styles.H4, 5f, 2f, 1.15f));
                 }
 
                 Target.EvaluatedCriterions.ForEach(item =>

pdf-generator/EvaluationReport/EvaluationResults.cs

@@ -34,7 +34,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds pillar information to document and goes through all its quality targets.
         /// </summary>
-        /// <param name="pillar"></param>
+        /// <param name="pillar">Pillar to render into the document.</param>
         private void RenderPillar(Pillar pillar)
         {
             Bookmarks.AddRootOutline(pillar.Heading, RootOutline);
@@ -56,7 +56,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds quality target information to document and goes through all its criteria.
         /// </summary>
-        /// <param name="qualityTarget"></param>
+        /// <param name="qualityTarget">Quality target to render into the document.</param>
         private void RenderQualityTarget(QualityTarget qualityTarget)
         {
             string section = qualityTarget.Paragraphs[0];
@@ -90,7 +90,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds criterion information to document and goes through all its kpi evaluations.
         /// </summary>
-        /// <param name="criterion"></param>
+        /// <param name="criterion">Criterion to render into the document.</param>
         private void RenderCriterion(Criterion criterion)
         {
             new CriterionTarget(criterion.CriterionTarget, Results.Sections[criterion.CriterionTarget.Paragraphs[0]], CustomUploads,
@@ -108,7 +108,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds a table for listing measures as part of the criterion information
         /// </summary>
-        /// <param name="measureTable">holds the information of each measure</param>
+        /// <param name="measureTable">Holds the information of each measure.</param>
         private void AddMeasureSection(MeasureTable measureTable)
         {
             Table table = new Table(UnitValue.CreatePercentArray(new float[] { 1f, 1f, 1f, 1f, 1f, 1f, 1f, 1f, 1f, 1f }), false)
@@ -129,30 +129,30 @@ namespace PDFGenerator.EvaluationReport
 
             measureTable.Measures.ForEach(measure =>
             {
-                //first row
+                // first row
                 table.AddCell(new Cell().Add(new Paragraph(new Text("Kriterium/ Kennzahl").AddStyle(Styles.SmallBold)).SetMultipliedLeading(1f)).SetPaddingBottom(0));
                 table.AddCell(new Cell(1, 4).Add(new Paragraph(new Text("Studiengang").AddStyle(Styles.SmallBold))).SetVerticalAlignment(VerticalAlignment.MIDDLE).SetPaddingBottom(0));
                 table.AddCell(new Cell().Add(new Paragraph(new Text("Fristigkeit").AddStyle(Styles.SmallBold))).SetVerticalAlignment(VerticalAlignment.MIDDLE).SetPaddingBottom(0));
                 table.AddCell(new Cell(1, 4).Add(new Paragraph(new Text("Zuständigkeit").AddStyle(Styles.SmallBold))).SetVerticalAlignment(VerticalAlignment.MIDDLE).SetPaddingBottom(0));
 
-                //spans rows 2-4 
+                // spans rows 2-4 
                 table.AddCell(new Cell(3, 1).Add(new Paragraph(new Text(measure.FullId).AddStyle(Styles.Small)).SetMultipliedLeading(1f)).SetPaddingBottom(0));
 
-                //second row
+                // second row
                 table.AddCell(new Cell(1, 4).Add(new Paragraph(new Text(measure.CourseName).AddStyle(Styles.Small)).SetMultipliedLeading(0.9f)).SetPaddingBottom(0));
                 table.AddCell(new Cell().Add(new Paragraph(new Text(measure.Maturity).AddStyle(Styles.Small)).SetMultipliedLeading(0.9f)).SetPaddingBottom(0));
                 table.AddCell(new Cell(1, 4).Add(new Paragraph(new Text(measure.Responsibilities).AddStyle(Styles.Small)).SetMultipliedLeading(0.9f)).SetPaddingBottom(0));
 
-                //third row
+                // third row
                 table.AddCell(new Cell(1, 4).Add(new Paragraph(new Text("Maßnahme").AddStyle(Styles.SmallBold)).SetMultipliedLeading(1f)).SetPaddingBottom(0));
                 table.AddCell(new Cell(1, 5).Add(new Paragraph(new Text("Kommentar").AddStyle(Styles.SmallBold)).SetMultipliedLeading(1f)).SetPaddingBottom(0));
 
-                //fourth row
+                // fourth row
                 table.AddCell(new Cell(1, 4).Add(new Paragraph(new Text(measure.Description).AddStyle(Styles.Small)).SetMultipliedLeading(0.9f)).SetPaddingBottom(0));
                 table.AddCell(new Cell(1, 5).Add(new Paragraph(new Text(measure.Comments).AddStyle(Styles.Small)).SetMultipliedLeading(0.9f)).SetPaddingBottom(0));
             });
 
-            // message for non-available measures, if available
+            // message for non-available measures if available
             if (measureTable.Measures.Count == 0 && measureTable.Paragraphs.Count > 1)
             {
                 table.AddCell(

pdf-generator/EvaluationReport/KpiEvaluation.cs

@@ -24,7 +24,7 @@ namespace PDFGenerator.EvaluationReport
         }
 
         /// <summary>
-        /// Renders the content regarding a single kpi and goes through als its reports.
+        /// Renders the content regarding a single kpi and iterates through its reports.
         /// </summary>
         public override void Render()
         {
@@ -66,7 +66,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds content about if the kpi is reached or not.
         /// </summary>
-        /// <param name="evaluatedKpis">holds information for each available course</param>
+        /// <param name="evaluatedKpis">Containing information for each available course.</param>
         private void AddKpiIsReachedSection(List<EvaluatedKpi> evaluatedKpis)
         {
             evaluatedKpis.ForEach(item =>
@@ -84,7 +84,7 @@ namespace PDFGenerator.EvaluationReport
                         color = new DeviceRgb(249, 210, 218);
                     }
 
-                    // avoid that existent multiple white spaces immediately after a line break are ignored from iText7
+                    // avoid that existent multiple whitespaces after a line break are ignored by iText7
                     Table panel = Panel.GetPanel(new Paragraph(new Text(PreserveLeadingSpaces(item.Paragraph)).AddStyle(Styles.Paragraph)), color);
                     cell.Add(panel);
                     Table.AddCell(cell);
@@ -95,7 +95,7 @@ namespace PDFGenerator.EvaluationReport
         /// <summary>
         /// Adds content about the kpi comment.
         /// </summary>
-        /// <param name="evaluatedKpis">holds information for each available course</param>
+        /// <param name="evaluatedKpis">Contains information for each available course.</param>
         private void AddKpiCommentSection(List<EvaluatedKpi> evaluatedKpis)
         {
             evaluatedKpis.ForEach(item =>

pdf-generator/EvaluationReport/KpiEvaluationReports.cs

@@ -126,7 +126,7 @@ namespace PDFGenerator.EvaluationReport
 
             AddPageBreak();
 
-            // if order between images and text important
+            // if order between images and text is important
             if (Reports.ReportElementOrder != null)
             {