diff --git a/change/@minecraft-api-docs-generator-72dc3fde-8170-4c70-80d3-8ec997ea737a.json b/change/@minecraft-api-docs-generator-72dc3fde-8170-4c70-80d3-8ec997ea737a.json new file mode 100644 index 0000000..3c3a63a --- /dev/null +++ b/change/@minecraft-api-docs-generator-72dc3fde-8170-4c70-80d3-8ec997ea737a.json @@ -0,0 +1,7 @@ +{ + "type": "minor", + "comment": "Added property and function argument bounds data to metadata", + "packageName": "@minecraft/api-docs-generator", + "email": "brandon.chan@skyboxlabs.com", + "dependentChangeType": "patch" +} diff --git a/change/@minecraft-markup-generators-plugin-ca1f3867-e66f-44bf-9e32-2ea263c692af.json b/change/@minecraft-markup-generators-plugin-ca1f3867-e66f-44bf-9e32-2ea263c692af.json new file mode 100644 index 0000000..06dbad4 --- /dev/null +++ b/change/@minecraft-markup-generators-plugin-ca1f3867-e66f-44bf-9e32-2ea263c692af.json @@ -0,0 +1,7 @@ +{ + "type": "minor", + "comment": "Added property and function argument bounds data to metadata", + "packageName": "@minecraft/markup-generators-plugin", + "email": "brandon.chan@skyboxlabs.com", + "dependentChangeType": "patch" +} diff --git a/tools/api-docs-generator-test-snapshots/test/bounds/__snapshots__/bounds.spec.ts.snap b/tools/api-docs-generator-test-snapshots/test/bounds/__snapshots__/bounds.spec.ts.snap new file mode 100644 index 0000000..1447474 --- /dev/null +++ b/tools/api-docs-generator-test-snapshots/test/bounds/__snapshots__/bounds.spec.ts.snap @@ -0,0 +1,622 @@ +// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html + +exports[`Bounds > Properly generates documentation for modules which contain bounds > # Of Files Generated 1`] = `9`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > msdocs/priorscriptapi/TOC.yml 1`] = ` +" - name: bounds-module 1.x.x + items: + - name: bounds-module 1.x.x + href: bounds-module-1xx/bounds-module.md + - name: ClassWithBounds + href: bounds-module-1xx/ClassWithBounds.md +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > msdocs/priorscriptapi/bounds-module-1xx/ClassWithBounds.md 1`] = ` +"--- +# DO NOT TOUCH — This file was automatically generated by @minecraft/api-docs-generator, to report problems file an issue at https://github.com/Mojang/minecraft-scripting-libraries +author: jakeshirley +ms.author: jashir +ms.service: minecraft-bedrock-edition +ms.date: 02/10/2025 +title: bounds-module-1xx.ClassWithBounds Class +description: Contents of the bounds-module.ClassWithBounds class (Version 1.x.x). +--- +# ClassWithBounds Class (Version 1.x.x) + +> [!IMPORTANT] +> This documentation is for an older version of this module. Go to the latest documentation [*here*](../../../scriptapi/bounds-module/ClassWithBounds.md). + +## Properties + +### **s** +\`s: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`-255\` + - This property can't be used in restricted-execution mode. + +### **t** +\`t: number;\` + +Type: *number* + +Notes: + - This property has a maximum bound of \`1\` + - This property can't be used in restricted-execution mode. + +### **u** +\`u: number;\` + +Type: *number* + +Notes: + - This property can't be used in restricted-execution mode. + +### **v** +\`v: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`-255\` + - This property has a maximum bound of \`-1\` + - This property can't be used in restricted-execution mode. + +### **w** +\`w: number;\` + +Type: *number* + +Notes: + - This property can't be used in restricted-execution mode. + +### **x** +\`x: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`1\` + - This property can't be used in restricted-execution mode. + +### **y** +\`y: number;\` + +Type: *number* + +Notes: + - This property has a maximum bound of \`255\` + - This property can't be used in restricted-execution mode. + +### **z** +\`z: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`1\` + - This property has a maximum bound of \`255\` + - This property can't be used in restricted-execution mode. + +## Methods +- [methodThatTakesBoundedValue](#methodthattakesboundedvalue) + +### **methodThatTakesBoundedValue** +\` +methodThatTakesBoundedValue(s: number, t: number, u: number, v: number, w: number, x: number, y: number, z: number): void +\` + +#### **Parameters** +- **s**: *number* + Minimum Bound: \`-255\` +- **t**: *number* + Maximum Bound: \`1\` +- **u**: *number* +- **v**: *number* + Minimum Bound: \`-255\` + Maximum Bound: \`-1\` +- **w**: *number* + Minimum Bound: \`1\` + Maximum Bound: \`255\` +- **x**: *number* + Minimum Bound: \`1\` +- **y**: *number* + Maximum Bound: \`255\` +- **z**: *number* + +**Returns** *void* + +Notes: +- This function can't be called in restricted-execution mode. +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > msdocs/priorscriptapi/bounds-module-1xx/bounds-module.md 1`] = ` +"--- +# DO NOT TOUCH — This file was automatically generated by @minecraft/api-docs-generator, to report problems file an issue at https://github.com/Mojang/minecraft-scripting-libraries +author: jakeshirley +ms.author: jashir +ms.service: minecraft-bedrock-edition +ms.date: 02/10/2025 +title: bounds-module-1xx Module +description: Contents of the bounds-module module (Version 1.x.x) +--- +# \`bounds-module\` Module (Version 1.x.x) + +> [!IMPORTANT] +> This documentation is for an older version of this module. Go to the latest documentation [*here*](../../../scriptapi/bounds-module/bounds-module.md). + +## Manifest Details +\`\`\`json +{ + "module_name": "bounds-module", + "version": "1.0.0" +} +\`\`\` + +## Available Versions +- \`1.0.0\` + +## Classes +- [ClassWithBounds](ClassWithBounds.md) +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > msdocs/scriptapi/TOC.yml 1`] = ` +" - name: bounds-module + items: + - name: bounds-module + href: bounds-module/bounds-module.md + - name: bounds-module Changelog + href: bounds-module/changelog.md + - name: ClassWithBounds + href: bounds-module/ClassWithBounds.md +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > msdocs/scriptapi/bounds-module/ClassWithBounds.md 1`] = ` +"--- +# DO NOT TOUCH — This file was automatically generated by @minecraft/api-docs-generator, to report problems file an issue at https://github.com/Mojang/minecraft-scripting-libraries +author: jakeshirley +ms.author: jashir +ms.service: minecraft-bedrock-edition +ms.date: 02/10/2025 +title: bounds-module.ClassWithBounds Class +description: Contents of the bounds-module.ClassWithBounds class. +--- +# ClassWithBounds Class + +## Properties + +### **s** +\`s: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`1\` + - This property can't be used in restricted-execution mode. + +### **t** +\`t: number;\` + +Type: *number* + +Notes: + - This property has a maximum bound of \`255\` + - This property can't be used in restricted-execution mode. + +### **u** +\`u: number;\` + +Type: *number* + +Notes: + - This property can't be used in restricted-execution mode. + +### **v** +\`v: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`1\` + - This property has a maximum bound of \`255\` + - This property can't be used in restricted-execution mode. + +### **w** +\`w: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`1\` + - This property has a maximum bound of \`255\` + - This property can't be used in restricted-execution mode. + +### **x** +\`x: number;\` + +Type: *number* + +Notes: + - This property has a maximum bound of \`255\` + - This property can't be used in restricted-execution mode. + +### **y** +\`y: number;\` + +Type: *number* + +Notes: + - This property has a minimum bound of \`1\` + - This property can't be used in restricted-execution mode. + +### **z** +\`z: number;\` + +Type: *number* + +Notes: + - This property can't be used in restricted-execution mode. + +## Methods +- [methodThatTakesBoundedValue](#methodthattakesboundedvalue) + +### **methodThatTakesBoundedValue** +\` +methodThatTakesBoundedValue(s: number, t: number, u: number, v: number, w: number, x: number, y: number, z: number): void +\` + +#### **Parameters** +- **s**: *number* + Minimum Bound: \`1\` +- **t**: *number* + Maximum Bound: \`255\` +- **u**: *number* +- **v**: *number* + Minimum Bound: \`1\` + Maximum Bound: \`255\` +- **w**: *number* +- **x**: *number* + Maximum Bound: \`255\` +- **y**: *number* + Minimum Bound: \`1\` +- **z**: *number* + Minimum Bound: \`1\` + Maximum Bound: \`255\` + +**Returns** *void* + +Notes: +- This function can't be called in restricted-execution mode. +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > msdocs/scriptapi/bounds-module/bounds-module.md 1`] = ` +"--- +# DO NOT TOUCH — This file was automatically generated by @minecraft/api-docs-generator, to report problems file an issue at https://github.com/Mojang/minecraft-scripting-libraries +author: jakeshirley +ms.author: jashir +ms.service: minecraft-bedrock-edition +ms.date: 02/10/2025 +title: bounds-module Module +description: Contents of the bounds-module module +--- +# \`bounds-module\` Module + +## [Changelog](changelog.md) + +## Manifest Details +\`\`\`json +{ + "module_name": "bounds-module", + "version": "2.0.0" +} +\`\`\` +This is version 2.x.x of this module, which is the latest as of version 1.0.0 of Minecraft. + +## Available Versions +- \`2.0.0\` + +### Prior Versions + +The following API versions are from a major version that is documented here: [*bounds-module*](../../../priorscriptapi/bounds-module-1xx/bounds-module.md): +- \`1.0.0\` + + +## Classes +- [ClassWithBounds](ClassWithBounds.md) +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > msdocs/scriptapi/bounds-module/changelog.md 1`] = ` +"--- +# DO NOT TOUCH — This file was automatically generated by @minecraft/api-docs-generator, to report problems file an issue at https://github.com/Mojang/minecraft-scripting-libraries +author: jakeshirley +ms.author: jashir +ms.service: minecraft-bedrock-edition +ms.date: 02/10/2025 +title: bounds-module Changelog +description: Changelog of the \`bounds-module\` module +--- +# \`bounds-module\` Changelog + +## Version Changes +- [2.0.0](#200) +- [1.0.0](#100) + +## 2.0.0 +#### Changed *[\`ClassWithBounds\`](ClassWithBounds.md)* +- Changed minimum bound of \`-255\` to \`1\` for property *[\`s\`](ClassWithBounds.md#s)* +- Changed maximum bound of \`1\` to \`255\` for property *[\`t\`](ClassWithBounds.md#t)* +- Changed minimum bound of \`-255\` to \`1\` for property *[\`v\`](ClassWithBounds.md#v)* +- Changed maximum bound of \`-1\` to \`255\` for property *[\`v\`](ClassWithBounds.md#v)* +- Added minimum bound of \`1\` for property *[\`w\`](ClassWithBounds.md#w)* +- Added maximum bound of \`255\` for property *[\`w\`](ClassWithBounds.md#w)* +- Removed minimum bound for property *[\`x\`](ClassWithBounds.md#x)* +- Added maximum bound of \`255\` for property *[\`x\`](ClassWithBounds.md#x)* +- Added minimum bound of \`1\` for property *[\`y\`](ClassWithBounds.md#y)* +- Removed maximum bound for *[\`y\`](ClassWithBounds.md#y)* +- Removed minimum bound for property *[\`z\`](ClassWithBounds.md#z)* +- Removed maximum bound for *[\`z\`](ClassWithBounds.md#z)* +- Changed function *[\`methodThatTakesBoundedValue\`](ClassWithBounds.md#methodthattakesboundedvalue)* + - Changed minimum bound from \`-255\` to \`1\` for argument \`s\` + - Changed maximum bound from \`1\` to \`255\` for argument \`t\` + - Changed minimum bound from \`-255\` to \`1\` for argument \`v\` + - Changed maximum bound from \`-1\` to \`255\` for argument \`v\` + - Removed minimum bound of \`1\` from argument \`w\` + - Removed maximum bound of \`255\` from argument \`w\` + - Removed minimum bound of \`1\` from argument \`x\` + - Added maximum bound of \`255\` to argument \`x\` + - Added minimum bound of \`1\` to argument \`y\` + - Removed maximum bound of \`255\` from argument \`y\` + - Added minimum bound of \`1\` to argument \`z\` + - Added maximum bound of \`255\` to argument \`z\` +## 1.0.0 +#### Added \`bounds-module\` Module +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > typescript/bounds-module@1.0.0.d.ts 1`] = ` +"// Type definitions for Minecraft Bedrock Edition script APIs +// Project: https://docs.microsoft.com/minecraft/creator/ +// Definitions by: Jake Shirley +// Mike Ammerlaan + +/* ***************************************************************************** + Copyright (c) Microsoft Corporation. + ***************************************************************************** */ +/** + * @packageDocumentation + * + * Manifest Details + * \`\`\`json + * { + * "module_name": "bounds-module", + * "version": "1.0.0" + * } + * \`\`\` + * + */ +export class ClassWithBounds { + private constructor(); + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: -255 + * + */ + s: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Maximum Value: 1 + * + */ + t: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + */ + u: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: -255 + * + * Maximum Value: -1 + * + */ + v: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + */ + w: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: 1 + * + */ + x: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Maximum Value: 255 + * + */ + y: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: 1 + * + * Maximum Value: 255 + * + */ + z: number; + /** + * @remarks + * This function can't be called in restricted-execution mode. + * + * @param s + * Minimum value: -255 + * @param t + * Maximum value: 1 + * @param v + * Minimum value: -255 + * Maximum value: -1 + * @param w + * Minimum value: 1 + * Maximum value: 255 + * @param x + * Minimum value: 1 + * @param y + * Maximum value: 255 + */ + methodThatTakesBoundedValue( + s: number, + t: number, + u: number, + v: number, + w: number, + x: number, + y: number, + z: number + ): void; +} +" +`; + +exports[`Bounds > Properly generates documentation for modules which contain bounds > typescript/bounds-module@2.0.0.d.ts 1`] = ` +"// Type definitions for Minecraft Bedrock Edition script APIs +// Project: https://docs.microsoft.com/minecraft/creator/ +// Definitions by: Jake Shirley +// Mike Ammerlaan + +/* ***************************************************************************** + Copyright (c) Microsoft Corporation. + ***************************************************************************** */ +/** + * @packageDocumentation + * + * Manifest Details + * \`\`\`json + * { + * "module_name": "bounds-module", + * "version": "2.0.0" + * } + * \`\`\` + * + */ +export class ClassWithBounds { + private constructor(); + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: 1 + * + */ + s: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Maximum Value: 255 + * + */ + t: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + */ + u: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: 1 + * + * Maximum Value: 255 + * + */ + v: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: 1 + * + * Maximum Value: 255 + * + */ + w: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Maximum Value: 255 + * + */ + x: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + * Minimum Value: 1 + * + */ + y: number; + /** + * @remarks + * This property can't be used in restricted-execution mode. + * + */ + z: number; + /** + * @remarks + * This function can't be called in restricted-execution mode. + * + * @param s + * Minimum value: 1 + * @param t + * Maximum value: 255 + * @param v + * Minimum value: 1 + * Maximum value: 255 + * @param x + * Maximum value: 255 + * @param y + * Minimum value: 1 + * @param z + * Minimum value: 1 + * Maximum value: 255 + */ + methodThatTakesBoundedValue( + s: number, + t: number, + u: number, + v: number, + w: number, + x: number, + y: number, + z: number + ): void; +} +" +`; diff --git a/tools/api-docs-generator-test-snapshots/test/bounds/bounds.spec.ts b/tools/api-docs-generator-test-snapshots/test/bounds/bounds.spec.ts new file mode 100644 index 0000000..ea36e3b --- /dev/null +++ b/tools/api-docs-generator-test-snapshots/test/bounds/bounds.spec.ts @@ -0,0 +1,14 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT License. + +import { describe, it } from 'vitest'; +import { runGeneratorForTest } from '../runGeneratorForTest'; + +describe('Bounds', () => { + it('Properly generates documentation for modules which contain bounds', () => { + runGeneratorForTest({ + testDir: __dirname, + generators: ['ts', 'msdocs'], + }); + }); +}); diff --git a/tools/api-docs-generator-test-snapshots/test/bounds/docs/sentinel b/tools/api-docs-generator-test-snapshots/test/bounds/docs/sentinel new file mode 100644 index 0000000..a5e30b1 --- /dev/null +++ b/tools/api-docs-generator-test-snapshots/test/bounds/docs/sentinel @@ -0,0 +1 @@ +// File exists to ensure docs folder exists diff --git a/tools/api-docs-generator-test-snapshots/test/bounds/input/test-module_v1.json b/tools/api-docs-generator-test-snapshots/test/bounds/input/test-module_v1.json new file mode 100644 index 0000000..ebebc2e --- /dev/null +++ b/tools/api-docs-generator-test-snapshots/test/bounds/input/test-module_v1.json @@ -0,0 +1,321 @@ +{ + "classes": [ + { + "name": "ClassWithBounds", + "properties": [ + { + "has_max": false, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": 2147483647, + "min_value": -255, + "name": "s", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": 1, + "min_value": -2147483648, + "name": "t", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": false, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": -1, + "min_value": -255, + "name": "u", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": -1, + "min_value": -255, + "name": "v", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": false, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": 2147483647, + "min_value": -2147483648, + "name": "w", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": false, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": 2147483647, + "min_value": 1, + "name": "x", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": 255, + "min_value": -2147483648, + "name": "y", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": 255, + "min_value": 1, + "name": "z", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + } + ], + "type": { + "is_bind_type": true, + "is_errorable": false, + "name": "ClassWithBounds" + }, + "functions": [ + { + "arguments": [ + { + "details": { + "has_max": false, + "has_min": true, + "max_value": 2147483647, + "min_value": -255 + }, + "name": "s", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": false, + "max_value": 1, + "min_value": -2147483648 + }, + "name": "t", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": false, + "has_min": false, + "max_value": -1, + "min_value": -255 + }, + "name": "u", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": true, + "max_value": -1, + "min_value": -255 + }, + "name": "v", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": true, + "max_value": 255, + "min_value": 1 + }, + "name": "w", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": false, + "has_min": true, + "max_value": 2147483647, + "min_value": 1 + }, + "name": "x", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": false, + "max_value": 255, + "min_value": -2147483648 + }, + "name": "y", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": false, + "has_min": false, + "max_value": 2147483647, + "min_value": -2147483648 + }, + "name": "z", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + } + ], + "is_constructor": false, + "name": "methodThatTakesBoundedValue", + "return_type": { + "is_bind_type": false, + "is_errorable": false, + "name": "void" + } + } + ] + } + ], + + "minecraft_version": "1.0.0", + "name": "bounds-module", + "uuid": "d79b396f-dc7a-46e0-97c5-a14434ab8dcd", + "version": "1.0.0", + "module_type": "script" +} diff --git a/tools/api-docs-generator-test-snapshots/test/bounds/input/test-module_v2.json b/tools/api-docs-generator-test-snapshots/test/bounds/input/test-module_v2.json new file mode 100644 index 0000000..6b3d759 --- /dev/null +++ b/tools/api-docs-generator-test-snapshots/test/bounds/input/test-module_v2.json @@ -0,0 +1,320 @@ +{ + "classes": [ + { + "name": "ClassWithBounds", + "properties": [ + { + "has_max": false, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": 2147483647, + "min_value": 1, + "name": "s", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": 255, + "min_value": -2147483648, + "name": "t", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + },{ + "has_max": false, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": 255, + "min_value": 1, + "name": "u", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": 255, + "min_value": 1, + "name": "v", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": 255, + "min_value": 1, + "name": "w", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": true, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": 255, + "min_value": -2147483648, + "name": "x", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": false, + "has_min": true, + "is_baked": false, + "is_read_only": false, + "max_value": 2147483647, + "min_value": 1, + "name": "y", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "has_max": false, + "has_min": false, + "is_baked": false, + "is_read_only": false, + "max_value": 2147483647, + "min_value": -2147483648, + "name": "z", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + } + ], + "type": { + "is_bind_type": true, + "is_errorable": false, + "name": "ClassWithBounds" + }, + "functions": [ + { + "arguments": [ + { + "details": { + "has_max": false, + "has_min": true, + "max_value": 2147483647, + "min_value": 1 + }, + "name": "s", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": false, + "max_value": 255, + "min_value": -2147483648 + }, + "name": "t", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": false, + "has_min": false, + "max_value": 255, + "min_value": 1 + }, + "name": "u", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": true, + "max_value": 255, + "min_value": 1 + }, + "name": "v", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": false, + "has_min": false, + "max_value": 2147483647, + "min_value": -2147483648 + }, + "name": "w", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": false, + "max_value": 255, + "min_value": -2147483648 + }, + "name": "x", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": false, + "has_min": true, + "max_value": 2147483647, + "min_value": 1 + }, + "name": "y", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + }, + { + "details": { + "has_max": true, + "has_min": true, + "max_value": 255, + "min_value": 1 + }, + "name": "z", + "type": { + "is_bind_type": false, + "is_errorable": false, + "name": "int32", + "valid_range": { + "max": 2147483647, + "min": -2147483648 + } + } + } + ], + "is_constructor": false, + "name": "methodThatTakesBoundedValue", + "return_type": { + "is_bind_type": false, + "is_errorable": false, + "name": "void" + } + } + ] + } + ], + + "minecraft_version": "1.0.0", + "name": "bounds-module", + "uuid": "d79b396f-dc7a-46e0-97c5-a14434ab8dcd", + "version": "2.0.0", + "module_type": "script" +} diff --git a/tools/api-docs-generator/src/changelog.ts b/tools/api-docs-generator/src/changelog.ts index 3f579a5..e0e7e9f 100644 --- a/tools/api-docs-generator/src/changelog.ts +++ b/tools/api-docs-generator/src/changelog.ts @@ -89,6 +89,10 @@ const scriptingDataLayout: RootMetadataScope = { key: 'name', submembers: { is_read_only: { type: 'value' }, + has_min: { type: 'value' }, + has_max: { type: 'value' }, + min_value: { type: 'value' }, + max_value: { type: 'value' }, get_privilege: { type: 'array', key: 'name' }, set_privilege: { type: 'array', key: 'name' }, type: TypeDataLayout, @@ -103,6 +107,9 @@ const scriptingDataLayout: RootMetadataScope = { key: 'name', submembers: { type: TypeDataLayout, + details: { + type: 'value', + }, }, }, call_privilege: { type: 'array', key: 'name' }, @@ -158,6 +165,9 @@ const scriptingDataLayout: RootMetadataScope = { key: 'name', submembers: { type: TypeDataLayout, + details: { + type: 'value', + }, }, }, return_type: TypeDataLayout, diff --git a/tools/api-docs-generator/src/filters/CommonFilters.ts b/tools/api-docs-generator/src/filters/CommonFilters.ts index 34f37f1..458d3a6 100644 --- a/tools/api-docs-generator/src/filters/CommonFilters.ts +++ b/tools/api-docs-generator/src/filters/CommonFilters.ts @@ -1714,6 +1714,185 @@ function typeFlags(releases: MinecraftRelease[]) { } } +/** + * Marks up APIs that have bound values. + */ +function boundValues(releases: MinecraftRelease[]) { + for (const release of releases) { + for (const scriptModule of release.script_modules) { + for (const classJson of scriptModule.classes ?? []) { + for (const functionJson of classJson.functions ?? []) { + for (const argumentJson of functionJson.arguments) { + if (!argumentJson.details) { + continue; + } + + if (argumentJson.details.has_min && argumentJson.details.min_value !== undefined) { + argumentJson.has_bounds = true; + } + + if (argumentJson.details.has_max && argumentJson.details.max_value !== undefined) { + argumentJson.has_bounds = true; + } + } + } + } + } + } +} + +/** + * Marks up APIs that have bound values. + */ +function boundChanges(releases: MinecraftRelease[]) { + for (const release of releases) { + for (const scriptModule of release.script_modules) { + if (!moduleHasChangelog(scriptModule)) { + continue; + } + + for (const changelog of scriptModule.changelog) { + for (const classJson of changelog.classes) { + for (const propertyJson of classJson.properties) { + const has_min = propertyJson.has_min as unknown as { + $old: boolean; + $new: boolean; + has_changes?: boolean; + }; + + const min_value = propertyJson.min_value as { + $old: unknown; + $new: unknown; + has_changes?: boolean; + }; + + if (has_min && min_value) { + if (has_min.$old === true && has_min.$new === true) { + if (min_value.$old && min_value.$new && min_value.$old !== min_value.$new) { + propertyJson.min_changed = true; + } else if (min_value.$old === undefined && min_value.$new) { + propertyJson.min_added = true; + } else if (min_value.$old && min_value.$new === undefined) { + propertyJson.min_removed = true; + } + } else if (has_min.$old === false && has_min.$new === true) { + if (min_value.$new !== undefined) { + propertyJson.min_added = true; + } + } else if (has_min.$old === true && has_min.$new === false) { + if (min_value.$old !== undefined) { + propertyJson.min_removed = true; + } + // Conversion to $old and $new failed, since no changes were made + } else if (propertyJson.has_min === true && min_value.$old !== min_value.$new) { + propertyJson.min_changed = true; + } + } + + const has_max = propertyJson.has_max as unknown as { + $old: boolean; + $new: boolean; + has_changes?: boolean; + }; + + const max_value = propertyJson.max_value as { + $old: unknown; + $new: unknown; + has_changes?: boolean; + }; + + if (has_max && max_value) { + if (has_max.$old === true && has_max.$new === true) { + if (max_value.$old && max_value.$new && max_value.$old !== max_value.$new) { + propertyJson.max_changed = true; + } else if (max_value.$old === undefined && max_value.$new) { + propertyJson.max_added = true; + } else if (max_value.$old && max_value.$new === undefined) { + propertyJson.max_removed = true; + } + } else if (has_max.$old === false && has_max.$new === true) { + if (max_value.$new !== undefined) { + propertyJson.max_added = true; + } + } else if (has_max.$old === true && has_max.$new === false) { + if (max_value.$old !== undefined) { + propertyJson.max_removed = true; + } + // Conversion to $old and $new failed, since no changes were made + } else if (propertyJson.has_max === true && max_value.$old !== max_value.$new) { + propertyJson.max_changed = true; + } + } + } + + for (const functionJson of classJson.functions) { + for (const argumentJson of functionJson.arguments) { + type ArgumentDetails = { + default_value: unknown; + has_min: boolean; + min_value: unknown; + has_max: boolean; + max_value: unknown; + supported_values: unknown; + }; + + const details = argumentJson.details as { + $old: ArgumentDetails; + $new: ArgumentDetails; + has_changes?: boolean; + } | null; + + if ( + details === undefined || + // eslint-disable-next-line unicorn/no-null + details === null || + (details.$old === undefined && details.$new === undefined) + ) { + continue; + } + + if (details.$old !== undefined && details.$new === undefined) { + if (details.$old.has_min && details.$old.min_value !== undefined) { + argumentJson.min_removed = true; + } + if (details.$old.has_max && details.$old.max_value !== undefined) { + argumentJson.max_removed = true; + } + continue; + } + + if (details.$old === undefined && details.$new !== undefined) { + if (details.$new.has_min && details.$new.min_value !== undefined) { + argumentJson.min_added = true; + } + if (details.$new.has_max && details.$new.max_value !== undefined) { + argumentJson.max_added = true; + } + continue; + } + + const validOldMin = details.$old.has_min && details.$old.min_value !== undefined; + const validOldMax = details.$old.has_max && details.$old.max_value !== undefined; + + const validNewMin = details.$new.has_min && details.$new.min_value !== undefined; + const validNewMax = details.$new.has_max && details.$new.max_value !== undefined; + + argumentJson.min_added = !validOldMin && validNewMin; + argumentJson.min_removed = validOldMin && !validNewMin; + argumentJson.min_changed = + validOldMin && validNewMin && details.$old.min_value !== details.$new.min_value; + argumentJson.max_added = !validOldMax && validNewMax; + argumentJson.max_removed = validOldMax && !validNewMax; + argumentJson.max_changed = + validOldMax && validNewMax && details.$old.max_value !== details.$new.max_value; + } + } + } + } + } + } +} + /** * Marks up APIs that have default values with 'has_defaults'. */ @@ -3383,6 +3562,8 @@ export const CommonFilters: FilterGroup = { ['block_filters', blockFilters], ['constant_values', constantValues], ['default_values', defaultValues], + ['bound_values', boundValues], + ['bound_changes', boundChanges], ['markup_categories', markupCategories], ['type_alias_markup', typeAliasMarkup], ['type_flags', typeFlags], diff --git a/tools/api-docs-generator/src/filters/TypeScriptFilters.ts b/tools/api-docs-generator/src/filters/TypeScriptFilters.ts index bcf4696..e70f181 100644 --- a/tools/api-docs-generator/src/filters/TypeScriptFilters.ts +++ b/tools/api-docs-generator/src/filters/TypeScriptFilters.ts @@ -327,6 +327,7 @@ function flagTSComments(obj: MarkupCommentFlags): void { if ( obj.has_comments || obj.has_defaults || + obj.has_bounds || obj.has_errors || obj.is_prerelease || obj.is_deprecated || @@ -346,7 +347,13 @@ function flagTSComments(obj: MarkupCommentFlags): void { obj.ts_has_remarks = false; } - if (obj.has_privilege_comments || obj.has_closure_privilege_type_comments || obj.has_defaults || obj.has_errors) { + if ( + obj.has_privilege_comments || + obj.has_closure_privilege_type_comments || + obj.has_defaults || + obj.has_bounds || + obj.has_errors + ) { obj.msdocs_has_comments = true; } } diff --git a/tools/api-docs-generator/src/modules/MinecraftScriptModule.ts b/tools/api-docs-generator/src/modules/MinecraftScriptModule.ts index 6b26e42..150addc 100644 --- a/tools/api-docs-generator/src/modules/MinecraftScriptModule.ts +++ b/tools/api-docs-generator/src/modules/MinecraftScriptModule.ts @@ -53,6 +53,7 @@ export const MarkupCommentFlagsValidator = Intersect( Record({ has_changes: Optional(Boolean), has_defaults: Optional(Boolean), + has_bounds: Optional(Boolean), has_errors: Optional(Boolean), prerelease: Optional(String), @@ -342,8 +343,18 @@ export const MinecraftPropertyRecord = Intersect( Record({ type: MinecraftTypeRecord, is_read_only: Boolean, + has_min: Optional(Boolean), + min_value: Optional(Unknown.Or(Null)), + has_max: Optional(Boolean), + max_value: Optional(Unknown.Or(Null)), is_baked: Optional(Boolean), default_value: Optional(Unknown.Or(Null)), + min_added: Optional(Boolean), + min_changed: Optional(Boolean), + min_removed: Optional(Boolean), + max_added: Optional(Boolean), + max_changed: Optional(Boolean), + max_removed: Optional(Boolean), // Runtime Markup property_name: Optional(String.Or(Null)), @@ -364,7 +375,9 @@ export function hasProperties(obj: object): obj is { properties: MinecraftProper export const MinecraftFunctionArgumentDetailsRecord = Record({ default_value: Optional(Unknown.Or(Null)), + has_min: Optional(Unknown.Or(Null)), min_value: Optional(Unknown.Or(Null)), + has_max: Optional(Unknown.Or(Null)), max_value: Optional(Unknown.Or(Null)), supported_values: Optional(Unknown.Or(Null)), }); @@ -376,6 +389,12 @@ export const MinecraftFunctionArgumentRecord = Intersect( Record({ type: MinecraftTypeRecord, details: Optional(MinecraftFunctionArgumentDetailsRecord.Or(Null)), + min_added: Optional(Boolean), + min_changed: Optional(Boolean), + min_removed: Optional(Boolean), + max_added: Optional(Boolean), + max_changed: Optional(Boolean), + max_removed: Optional(Boolean), // Runtime Markup argument_description: Optional(Array(String).Or(Null)), diff --git a/tools/markup-generators-plugin/templates/msdocs/script/function.mustache b/tools/markup-generators-plugin/templates/msdocs/script/function.mustache index 5ad7225..bd6dce3 100644 --- a/tools/markup-generators-plugin/templates/msdocs/script/function.mustache +++ b/tools/markup-generators-plugin/templates/msdocs/script/function.mustache @@ -18,6 +18,14 @@ #### **Parameters** {{#arguments}} - **{{{name}}}**{{#type}}{{#is_optional}}?{{/is_optional}}: {{> type_with_links}}{{/type}}{{#details.default_value}} = `{{> value}}`{{/details.default_value}} + {{#details}} + {{#has_min}} + Minimum Bound: `{{min_value}}` + {{/has_min}} + {{#has_max}} + Maximum Bound: `{{max_value}}` + {{/has_max}} + {{/details}} {{#details.supported_values.length}} Supported values: [{{#details.supported_values}}{{> value}}{{^is_last}}, {{/is_last}}{{/details.supported_values}}] diff --git a/tools/markup-generators-plugin/templates/msdocs/script/module_changelog.mustache b/tools/markup-generators-plugin/templates/msdocs/script/module_changelog.mustache index 7f1cb4e..b7f241f 100644 --- a/tools/markup-generators-plugin/templates/msdocs/script/module_changelog.mustache +++ b/tools/markup-generators-plugin/templates/msdocs/script/module_changelog.mustache @@ -90,7 +90,25 @@ description: Changelog of the `{{{name}}}` module {{#$changed}} - Changed read-only flag for *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* from `{{{$old}}}` to `{{{$new}}}` {{/$changed}} - {{/is_read_only}} + {{/is_read_only}} + {{#min_added}} +- Added minimum bound of `{{{min_value.$new}}}` for property *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* + {{/min_added}} + {{#min_changed}} +- Changed minimum bound of `{{{min_value.$old}}}` to `{{{min_value.$new}}}` for property *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* + {{/min_changed}} + {{#min_removed}} +- Removed minimum bound for property *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* + {{/min_removed}} + {{#max_added}} +- Added maximum bound of `{{{max_value.$new}}}` for property *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* + {{/max_added}} + {{#max_changed}} +- Changed maximum bound of `{{{max_value.$old}}}` to `{{{max_value.$new}}}` for property *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* + {{/max_changed}} + {{#max_removed}} +- Removed maximum bound for *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* + {{/max_removed}} {{#type}} {{#$changed}} - Changed type for *[`{{{name}}}`]({{class_name}}.md#{{bookmark_name}})* from {{#$old.type}}{{> type_with_links}}{{#is_errorable}} (throws exceptions){{/is_errorable}}{{/$old.type}} to {{#$new.type}}{{> type_with_links}}{{#is_errorable}} (throws exceptions){{/is_errorable}}{{/$new.type}} @@ -141,6 +159,26 @@ description: Changelog of the `{{{name}}}` module {{/$changed}} {{/type}} {{/$removed}}{{/$added}} + {{#details}} + {{#min_added}} + - Added minimum bound of `{{{$new.min_value}}}` to argument `{{{name}}}` + {{/min_added}} + {{#min_changed}} + - Changed minimum bound from `{{{$old.min_value}}}` to `{{{$new.min_value}}}` for argument `{{{name}}}` + {{/min_changed}} + {{#min_removed}} + - Removed minimum bound of `{{{$old.min_value}}}` from argument `{{{name}}}` + {{/min_removed}} + {{#max_added}} + - Added maximum bound of `{{{$new.max_value}}}` to argument `{{{name}}}` + {{/max_added}} + {{#max_changed}} + - Changed maximum bound from `{{{$old.max_value}}}` to `{{{$new.max_value}}}` for argument `{{{name}}}` + {{/max_changed}} + {{#max_removed}} + - Removed maximum bound of `{{{$old.max_value}}}` from argument `{{{name}}}` + {{/max_removed}} + {{/details}} {{/arguments}} {{/$removed}}{{/$added}}{{/has_changes}} {{/functions}} diff --git a/tools/markup-generators-plugin/templates/msdocs/script/property.mustache b/tools/markup-generators-plugin/templates/msdocs/script/property.mustache index 90675dc..f36ebcd 100644 --- a/tools/markup-generators-plugin/templates/msdocs/script/property.mustache +++ b/tools/markup-generators-plugin/templates/msdocs/script/property.mustache @@ -26,6 +26,12 @@ Notes: - This property defaults to `{{> value}}` when undefined. {{/default_value}} {{/has_defaults}} + {{#has_min}} + - This property has a minimum bound of `{{min_value}}` + {{/has_min}} + {{#has_max}} + - This property has a maximum bound of `{{max_value}}` + {{/has_max}} {{#set_disallowed_in_restricted_execution}} {{#get_disallowed_in_restricted_execution}} - This property can't be used in restricted-execution mode. diff --git a/tools/markup-generators-plugin/templates/tsdef/function.mustache b/tools/markup-generators-plugin/templates/tsdef/function.mustache index 18fac85..7fa4154 100644 --- a/tools/markup-generators-plugin/templates/tsdef/function.mustache +++ b/tools/markup-generators-plugin/templates/tsdef/function.mustache @@ -48,6 +48,12 @@ * Defaults to: {{> value}} {{/details.default_value}} {{/has_defaults}} + {{#details.has_min}} + * Minimum value: {{details.min_value}} + {{/details.has_min}} + {{#details.has_max}} + * Maximum value: {{details.max_value}} + {{/details.has_max}} {{/ts_has_comments}} {{/arguments}} {{#returns_description_ts.length}} diff --git a/tools/markup-generators-plugin/templates/tsdef/property.mustache b/tools/markup-generators-plugin/templates/tsdef/property.mustache index a42db42..6e951b7 100644 --- a/tools/markup-generators-plugin/templates/tsdef/property.mustache +++ b/tools/markup-generators-plugin/templates/tsdef/property.mustache @@ -66,6 +66,18 @@ * {{/default_value}} {{/has_defaults}} + {{#has_min}} + {{#min_value}} + * Minimum Value: {{min_value}} + * + {{/min_value}} + {{/has_min}} + {{#has_max}} + {{#max_value}} + * Maximum Value: {{max_value}} + * + {{/max_value}} + {{/has_max}} {{#throws_description_ts.length}} * @throws {{#throws_description_ts}}