fine-tuned the comment validator, split out the logic for comments on…

… specific blocks
microsoft · Jan 31, 2024 · e61b971 · e61b971
1 parent 50b02ff
commit e61b971
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 11 deletions.
diff --git a/docs/teachertool/catalog-shared.json b/docs/teachertool/catalog-shared.json
@@ -13,10 +13,16 @@
             "docPath": "/teachertool"
         },
         {
-            "id": "49262A2B-C02A-43A2-BAD5-FCAC6AE9D465",
+            "id": "76D86387-E3CF-4BEB-B62C-B811F5997631",
             "use": "block_comment_used",
             "template": "At least one comment was left on a block in the code",
             "docPath": "/teachertool"
+        },
+        {
+            "id": "8F97C9A6-CF16-48B4-A84F-3105C24B20DE",
+            "use": "functions_have_comments",
+            "template": "All function definitions have block comments",
+            "docPath": "/teachertool"
         }
     ]
 }
diff --git a/docs/teachertool/validator-plans-shared.json b/docs/teachertool/validator-plans-shared.json
@@ -32,14 +32,25 @@
             ]
         },
         {
-            ".desc": "A comment exists in a project",
+            ".desc": "A block comment exists in a project",
             "name": "block_comment_used",
             "threshold": 1,
             "checks": [
                 {
                     "validator": "blockCommentExists"
                 }
             ]
+        },
+        {
+            ".desc": "All function definitions have block comments",
+            "name": "functions_have_comments",
+            "threshold": 1,
+            "checks": [
+                {
+                    "validator": "blockCommentExists",
+                    "blockType": "function_definition"
+                }
+            ]
         }
     ]
 }
diff --git a/pxtblocks/code-validation/runValidatorPlanAsync.ts b/pxtblocks/code-validation/runValidatorPlanAsync.ts
@@ -10,7 +10,7 @@ namespace pxt.blocks {
                 case "blocksExist":
                     return runBlocksExistValidation(usedBlocks, check as BlocksExistValidatorCheck);
                 case "blockCommentExists":
-                    return validateCommentsExist(usedBlocks);
+                    return runValidateBlockCommentsExist(usedBlocks, check as BlockCommentExistsValidatorCheck);
                 default:
                     pxt.debug(`Unrecognized validator: ${check.validator}`);
                     return false;
@@ -38,9 +38,12 @@ namespace pxt.blocks {
         return success;
     }
 
-    function runValidateCommentsExist(usedBlocks: Blockly.Block[], inputs: BlockCommentExistsValidatorCheck): boolean {
-        const blockResults = validateCommentsExist(usedBlocks);
-
-        return true;
+    function runValidateBlockCommentsExist(usedBlocks: Blockly.Block[], inputs: BlockCommentExistsValidatorCheck): boolean {
+        const blockTypeUsed = inputs.blockType;
+        const blockResults = blockTypeUsed ?
+            validateCommentsOnSpecificBlocksExist({ usedBlocks, blockType: blockTypeUsed }) :
+            validateBlockCommentsExist({ usedBlocks });
+        const success = blockTypeUsed ? blockResults.length === 0 : blockResults.length !== 0;
+        return success;
     }
 }
diff --git a/pxtblocks/code-validation/validateCommentsExist.ts b/pxtblocks/code-validation/validateCommentsExist.ts
@@ -1,7 +1,20 @@
 
 namespace pxt.blocks {
-    export function validateCommentsExist(usedBlocks: Blockly.Block[]): boolean {
-        const commentBlocks = usedBlocks.filter((block) => !!block.comment);
-        return commentBlocks.length > 0;
+    // validates that one or more blocks comments are in the project
+    // returns the blocks that have comments for teacher tool scenario
+    export function validateBlockCommentsExist({ usedBlocks }: { usedBlocks: Blockly.Block[] }): Blockly.Block[] {
+        const commentBlocks = usedBlocks.filter((block) => !!block.getCommentText());
+        return commentBlocks;
+    }
+
+    // validates that all of a specific block type have comments
+    // returns the blocks that do not have comments for a tutorial validation scenario
+    export function validateCommentsOnSpecificBlocksExist({ usedBlocks, blockType }: {
+            usedBlocks: Blockly.Block[],
+            blockType: string,
+        }): Blockly.Block[] {
+        const allSpecifcBlocks = usedBlocks.filter((block) => block.type === blockType);
+        const noncommentBlocks = allSpecifcBlocks.filter((block) => !block.getCommentText());
+        return noncommentBlocks;
     }
 }
diff --git a/pxtblocks/code-validation/validatorPlans.ts b/pxtblocks/code-validation/validatorPlans.ts
@@ -20,6 +20,6 @@ namespace pxt.blocks {
 
     export interface BlockCommentExistsValidatorCheck extends ValidatorCheckBase {
         validator: "blockCommentExists";
-        onBlocks?: pxt.Map<number>;
+        blockType?: string;
     }
 }