Skip to content

Commit

Permalink
Update Code Validation Docs to Include Validate-Exists Marker (#9772)
Browse files Browse the repository at this point in the history
Wanted to update the docs to include the changes made in #9675.

These can now be utilized in Minecraft to validate non-highlighted blocks, which is nice!
  • Loading branch information
thsparks authored Nov 6, 2023
1 parent 7ae3806 commit e2ef9cb
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 2 deletions.
16 changes: 16 additions & 0 deletions docs/writing-docs/snippets.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,28 @@ you can add the namespace it should open in parentheses after the normal one

This will appear in tutorials as the `variables` category, but clicking it will toggle the `sprites` category.

### validate-exists

The ``@validate-exists`` tag marks the code block following it as subject to validation. This means that, when [code validation](/writing-docs/tutorials/basics.md#code-validation-validationlocal-and-validationglobal-sections) is enabled in a tutorial, the user is warned that their code isn't matching a block that the tutorial intended.

Use `// @validate-exists` in blocks and TypeScript, and `# @validate-exists`
in Python.

````
```blocks
// @validate-exists
basic.showString("HELLO!")
```
````

### highlight

When used in snippets, the renderer will higlight the next line of code or block following a comment containing
**@highlight**. Use `// @highlight` in blocks and TypeScript, and `# @highlight`
in Python.

Another feature of **@highlight**, like with **@validate-exists**, is that the highlighted block is also validated when [code validation](/writing-docs/tutorials/basics.md#code-validation-validationlocal-and-validationglobal-sections) is enabled.

````
```blocks
console.log(":)")
Expand Down
15 changes: 13 additions & 2 deletions docs/writing-docs/tutorials/basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,9 +275,11 @@ Within a validation section, you may specify which validators you want to enable

### Validators

Currently, only one validator exists: the `BlocksExistValidator`. This validator looks at [highlighted blocks](../snippets.md#highlight) in the answer key and confirms that, for each highlighted block, the user's code contains at least one block of the same type. It does *not* validate the parameters passed into the block.
Currently, only one validator exists for [highlight](/writing-docs/snippets.md#highlight) and [validate-exists](/writing-docs/snippets#validate-exists) blocks, the `BlocksExistValidator`. This validator looks at blocks tagged with `//@validate-exists` or `//@highlight` comments in the answer key and confirms that, for each tagged block, the user's code contains at least one block of the same type. It does *not* validate the parameters passed into the block.

The only property currently available on the `BlocksExistValidator` is `Enabled`, which determines whether or not the validator runs. This is `true` by default whenever you specify the validator but can be set to `false` if you wish to disable it on a single step.
You can specify whether the `BlocksExistValidator` checks for `//@validate-exists` or `//@highlight` using the `markers` property on the validator. If you specify only `validate-exists`, then highlighted blocks will not be validated. Similarly, if you specify only `highlight`, then blocks marked with `validate-exists` will not be checked. By default, both checks are enabled.

The `BlocksExistValidator` also has an `Enabled` property that determines whether or not the validator runs at all. This is `true` by default whenever you specify the validator but can be set to `false` if you wish to disable it on a single step.

### Examples
**Enable the `BlocksExistValidator` globally**
Expand All @@ -287,6 +289,15 @@ The only property currently available on the `BlocksExistValidator` is `Enabled`
```
````

**Enable the `BlocksExistValidator` globally and ignore highlighted blocks**
_Note: highlight is not specified in the markers property._
````
```validation.global
# BlocksExistValidator
* markers: validate-exists
```
````

**Disable the `BlocksExistValidator` on a single step, if it has been enabled globally**
````
```validation.local
Expand Down

0 comments on commit e2ef9cb

Please sign in to comment.