Merge remote-tracking branch 'upstream/master'

src/app/core/models/templates/section-parsers/common-parsers.model.ts

@@ -3,6 +3,31 @@ const { char, choice, coroutine, everyCharUntil, str, whitespace } = require('ar
 const TEAM_RESPONSE_HEADER = "# Team's Response";
 const DEFAULT_TEAM_RESPONSE = 'No details provided by team.';
 
+/**
+ * Builds a parser for the team response section.
+ * Team response sections appear in both the Team Response and Tester Response comment templates.
+ * The format of the Team Response section is as follows
+ * # Team's response
+ *
+ * { team's response }
+ *
+ * { next header }
+ *
+ * A concrete example would be:
+ *
+ * # Team's response
+ *
+ * This not a bug, it's a feature
+ *
+ * ## Duplicate status (if any):
+ *
+ * This parser works by reading everything in between the Team's reponse header and the next header.
+ * The reason why this parser builder exists is because the next header is different in both comment templates.
+ * The next header in the Team Response comment is ## Duplicate status (if any):
+ * While the next header in the Tester Response comment is # Disputes
+ * @param nextHeader
+ * @returns a string containing the team response
+ */
 export function buildTeamResponseSectionParser(nextHeader: string) {
   return coroutine(function* () {
     yield str(TEAM_RESPONSE_HEADER);
@@ -12,6 +37,13 @@ export function buildTeamResponseSectionParser(nextHeader: string) {
   });
 }
 
+/**
+ * Parses the checkbox and returns whether it is filled or not.
+ * Filled checkboxes look like this: - [x] { description }, e.g. - [x] I disagree
+ * Unfilled checkboxes look like thsi: - [ ] { description }
+ * @param description
+ * @returns true if the checkbox is filled, false otherwise
+ */
 export function buildCheckboxParser(description: string) {
   return coroutine(function* () {
     yield str('- [');

src/app/core/models/templates/section-parsers/issue-dispute-section-parser.model.ts

@@ -1,3 +1,37 @@
+/**
+ * An issue dispute section has the following format:
+ *
+ * ## :question: Issue { type of verification }
+ *
+ * ### Team says:
+ *
+ * { team's action that is being disputed }
+ *
+ * ### Tester says:
+ *
+ * { tester's objection }
+ *
+ * <catcher-end-of-segment><hr>
+ *
+ * A concrete example would be:
+ *
+ * ## :question: Issue type
+ *
+ * ### Team says:
+ *
+ * Team chose [`type.DocumentationBug`].
+ * Originally [`type.FunctionalityBug`].
+ *
+ * This use case is just not in the docs.
+ *
+ * ### Tester says:
+ *
+ * It's not a use case, it's a bug! This has nothing to do with the docs.
+ *
+ * <catcher-end-of-segment><hr>
+ *
+ */
+
 import { IssueDispute } from '../../issue-dispute.model';
 
 const { coroutine, everyCharUntil, optionalWhitespace, str } = require('arcsecond');

src/app/core/models/templates/section-parsers/moderation-section-parser.model.ts

@@ -1,3 +1,21 @@
+/**
+ * A Tutor Moderation section has this format:
+ *
+ * ## :question: Issue { type of verification }
+ * - [ ] Done
+ *
+ * { tutor response }
+ *
+ * <catcher-end-of-segment><hr>
+ *
+ * A concrete example would be:
+ *
+ * ## :question: Issue type
+ * - [x] Done
+ *
+ * I think it's all cool
+ */
+
 import { Checkbox } from '../../checkbox.model';
 import { IssueDispute } from '../../issue-dispute.model';
 import { buildCheckboxParser } from './common-parsers.model';

src/app/core/models/templates/section-parsers/tester-response-section-parser.model.ts

@@ -1,3 +1,33 @@
+/**
+ * A tester response section generally has this format (apart from the duplicate issue section)
+ *
+ * ## :question: Issue {type of verification}
+ *
+ * Team chose [{ team response }].
+ * Originally [{ tester response }].
+ *
+ * - [ ] I disagree
+ *
+ * **Reason for disagreement:**
+ * { disagreement reason }
+ *
+ * <catcher-end-of-segment><hr>
+ *
+ * A concrete example would be:
+ *
+ * ## :question: Issue severity
+ *
+ * Team chose [`severity.Low`].
+ * Originally [`severity.Medium`].
+ *
+ * - [x] I disagree
+ *
+ * **Reason for disagreement:**
+ * The team is silly and doesn't understand how bad this bug is!!!
+ *
+ * <catcher-end-of-segment><hr>
+ */
+
 import { buildCheckboxParser } from './common-parsers.model';
 
 const {
@@ -24,6 +54,12 @@ const DUPLICATE_STATUS_MESSAGE =
 
 export const DisagreeCheckboxParser = buildCheckboxParser(DISAGREE_CHECKBOX_DESCRIPTION);
 
+/**
+ * This parser extracts the response for the item disagreed on.
+ * E.g. for [`severity.Low`], the category is 'severity' and the parser would return 'Low'
+ * @param category
+ * @returns a string indicating the response in that category
+ */
 function buildExtractResponseParser(category: string) {
   return between(str('[`' + category + '.'))(str('`]'))(letters);
 }
@@ -48,7 +84,21 @@ export const DisagreeReasonParser = coroutine(function* () {
   return reasonForDisagreement.trim();
 });
 
-// Issue duplicate section has a different format than the other three
+/**
+ * The duplicate issue section has a different format than the other three, which is below:
+ *
+ * ## :question: Issue duplicate status
+ *
+ * Team chose to mark this issue as a duplicate of another issue (as explained in the _**Team's response**_ above)
+ *
+ *
+ *
+ * - [ ] I disagree
+ *
+ * **Reason for disagreement:** [replace this with your explanation]
+ *
+ * <catcher-end-of-segment><hr>
+ */
 const DuplicateSectionParser = coroutine(function* () {
   yield str('status');
   yield whitespace;
@@ -93,7 +143,7 @@ export const TesterResponseSectionParser = coroutine(function* () {
 
   const teamChose = yield teamResponseParser;
   yield whitespace;
-  // response section does not have tester response
+  // response section does not have tester response, i.e. no "Originally [`response.Something`]"
   const testerChose = yield possibly(testerResponseParser);
   yield optionalWhitespace;
 

src/app/core/models/templates/team-accepted-template.model.ts

@@ -1,3 +1,9 @@
+/**
+ * A Team Accepted comment has this format:
+ *
+ * Your response not required for this bug as the team has accepted the bug as it is.
+ */
+
 import { GithubComment } from '../github/github-comment.model';
 import { Template } from './template.model';
 

src/app/core/models/templates/team-response-template.model.ts

@@ -1,3 +1,22 @@
+/**
+ * A Team Response comment has the following format:
+ *
+ * # Team's response
+ *
+ * { team's response }
+ *
+ * ## Duplicate status (if any):
+ * { duplicate issue number, or '--' if not a duplicate }
+ *
+ * A concrete example would be:
+ *
+ * # Team's response
+ *
+ * This is not a bug, it's a feature
+ *
+ * ## Duplicate status (if any):
+ * Duplicate of #42
+ */
 import { IssueComment } from '../comment.model';
 import { GithubComment } from '../github/github-comment.model';
 import { buildTeamResponseSectionParser } from './section-parsers/common-parsers.model';

src/app/core/models/templates/template.model.ts

@@ -1,3 +1,7 @@
+/**
+ * Comment template formats can be found at https://catcher-org.github.io/dg/user-workflow.html
+ */
+
 import { GithubComment } from '../github/github-comment.model';
 
 export abstract class Template {

src/app/core/models/templates/tester-response-template.model.ts

@@ -1,3 +1,53 @@
+/**
+ * A Tester Response comment has the following format:
+ *
+ * [IMPORTANT!: Please do not edit or reply to this comment using the GitHub UI. \
+      You can respond to it using CATcher during the next phase of the PE]
+ *
+ * # Team's response
+ *
+ * { team's response }
+ *
+ * # Items for the Tester to Verify
+ *
+ * { 1 or more Tester Response sections, see tester-response-section-parser.model.ts }
+ *
+ * A concrete example would be:
+ *
+ * [IMPORTANT!: Please do not edit or reply to this comment using the GitHub UI. \
+      You can respond to it using CATcher during the next phase of the PE]
+ *
+ * # Team's response
+ *
+ * This is not a bug, it's a feature
+ *
+ * # Items for the Tester to Verify
+ *
+ * ## :question: Issue type
+ *
+ * Team chose [`type.DocumentationBug`].
+ * Originally [`type.FunctionalityBug`].
+ *
+ * [x] - I disagree
+ *
+ * **Reason for disagreement:**
+ * It's not a use case, it's a bug! This has nothing to do with the docs.
+ *
+ * <catcher-end-of-segment><hr>
+ *
+ * ## :question: Issue severity
+ *
+ * Team chose [`severity.VeryLow`].
+ * Originally [`severity.High`].
+ *
+ * [x] - I disagree
+ *
+ * **Reason for disagreement:**
+ * You don't understand how frustrating this bug is!!
+ *
+ * <catcher-end-of-segment><hr>
+ */
+
 import { IssueComment } from '../comment.model';
 import { GithubComment } from '../github/github-comment.model';
 import { TesterResponse } from '../tester-response.model';

src/app/core/models/templates/tutor-moderation-issue-template.model.ts

@@ -1,3 +1,52 @@
+/**
+ * A Tutor Moderation Issue comment has this format:
+ *
+ * # Issue Description
+ * { original issue description }
+ *
+ * # Team's Response
+ * { team's response}
+ *
+ * # Disputes
+ *
+ * { 1 or more Issue Dispute sections, see issue-dispute-section-parser.model.ts }
+ *
+ * A concrete example would be:
+ *
+ * # Issue Description
+ * This feature doesn't work when I enter this input!
+ *
+ * # Team's Response
+ * This is not a bug, it is a feature
+ *
+ * # Disputes
+ *
+ * ## :question: Issue type
+ *
+ * Team chose [`type.DocumentationBug`].
+ * Originally [`type.FunctionalityBug`].
+ *
+ * This use case is just not in the docs.
+ *
+ * ### Tester says:
+ *
+ * It's not a use case, it's a bug! This has nothing to do with the docs.
+ *
+ * <catcher-end-of-segment><hr>
+ *
+ * ## :question: Issue severity
+ *
+ * Team chose [`severity.VeryLow`].
+ * Originally [`severity.High`].
+ *
+ * This only affects users a tiny little bit.
+ *
+ * ### Tester says:
+ * You don't understand how frustrating this bug is!!
+ *
+ * <catcher-end-of-segment><hr>
+ */
+
 import { GithubIssue } from '../github/github-issue.model';
 import { IssueDispute } from '../issue-dispute.model';
 import { buildTeamResponseSectionParser } from './section-parsers/common-parsers.model';

src/app/core/models/templates/tutor-moderation-todo-template.model.ts

@@ -1,3 +1,27 @@
+/**
+ * A Tutor Moderation Todo comment has this format:
+ *
+ * # Tutor Moderation
+ *
+ * { 1 or more Tutor Moderation sections, see moderation-section-parser.model.ts }
+ *
+ * A concrete example would be:
+ *
+ * # Tutor Moderation
+ *
+ * ## :question: Issue severity
+ * - [x] Done
+ *
+ * I think it is justified.
+ *
+ * <catcher-end-of-segment><hr>
+ *
+ * ## :question: Issue type
+ * - [ ] Done
+ *
+ * <catcher-end-of-segment><hr>
+ */
+
 import { IssueComment } from '../comment.model';
 import { GithubComment } from '../github/github-comment.model';
 import { IssueDispute } from '../issue-dispute.model';