Skip to content

Commit a06c2f7

Browse files
SBLMikeDemoneSBLMikeDemone
authored
Fix MSDocs to properly distinguish undefined vs void (#81)
* Fix tsdef generator and msdocs generator to properly recognize void vs undefined * Change files * Void wasn't bolded! * Make changelog clearer for api docs generator * Fix the nit * Ensure test changes cause turbo to invalidate the cache
1 parent 7dee3e3 commit a06c2f7

File tree

10 files changed

+76
-10
lines changed

10 files changed

+76
-10
lines changed

‎change/@minecraft-api-docs-generator-b9350535-0e8f-42d6-b106-bc60dcd02f31.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"type": "patch",
3+
"comment": "Mark up void return types with 'is_void_return' and remove 'is_undefined' from them.",
4+
"packageName": "@minecraft/api-docs-generator",
5+
"email": "[email protected]",
6+
"dependentChangeType": "patch"
7+
}

‎change/@minecraft-markup-generators-plugin-cd6647b7-123c-48e5-b1fd-b83cbc3b1cc2.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"type": "patch",
3+
"comment": "Fix tsdef generator and msdocs generator to properly recognize void vs undefined",
4+
"packageName": "@minecraft/markup-generators-plugin",
5+
"email": "[email protected]",
6+
"dependentChangeType": "patch"
7+
}

‎tools/api-docs-generator-test-snapshots/test/closures/__snapshots__/closures.spec.ts.snap

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ description: Contents of the closure-tests.ExampleClass class.
3131
3232
Type: (arg0: *boolean* | *number*) => *void*
3333
34+
### **closureWithVariantUndefinedArg**
35+
\`read-only closureWithVariantUndefinedArg: (arg0: number | undefined) => number | undefined;\`
36+
37+
Type: (arg0: *number* | *undefined*) => *number | undefined*
38+
3439
## Methods
3540
- [constructor](#constructor)
3641
- [methodWithMultiArgClosure](#methodwithmultiargclosure)
@@ -109,6 +114,7 @@ exports[`Closures > Generates correct output closures > typescript/closure-tests
109114
*/
110115
export class ExampleClass {
111116
readonly closureWithVariantArg?: (arg0: boolean | number) => void;
117+
readonly closureWithVariantUndefinedArg: (arg0: number | undefined) => number | undefined;
112118
constructor(onChange?: (arg0: boolean | number) => void);
113119
methodWithMultiArgClosure(callback?: (arg0: boolean, arg1: number) => void): ExampleClass;
114120
}

‎tools/api-docs-generator-test-snapshots/test/closures/input/test-script-module.json

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,46 @@
154154
"name": "closure"
155155
}
156156
}
157+
},
158+
{
159+
"is_read_only": true,
160+
"name": "closureWithVariantUndefinedArg",
161+
"type": {
162+
"closure_type": {
163+
"argument_types": [
164+
{
165+
"is_bind_type": false,
166+
"is_errorable": false,
167+
"name": "variant",
168+
"variant_types": [
169+
{
170+
"is_bind_type": false,
171+
"is_errorable": false,
172+
"name": "float",
173+
"valid_range": {
174+
"max": 2147483647,
175+
"min": -2147483648
176+
}
177+
},
178+
179+
{
180+
"is_bind_type": false,
181+
"is_errorable": false,
182+
"name": "undefined"
183+
}
184+
]
185+
}
186+
],
187+
"return_type": {
188+
"is_bind_type": false,
189+
"is_errorable": true,
190+
"name": "number | undefined"
191+
}
192+
},
193+
"is_bind_type": false,
194+
"is_errorable": false,
195+
"name": "closure"
196+
}
157197
}
158198
],
159199
"type": {

‎tools/api-docs-generator-test-snapshots/turbo.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
"plugin/*.ts",
77
"test/*.ts",
88
"test/**/*.spec.ts",
9-
"test/**/*input*",
10-
"test/**/*docs*"
9+
"test/**/*input*/**",
10+
"test/**/*docs*/**"
1111
],
1212
"outputs": [
1313
"test/**/*output",

‎tools/api-docs-generator/src/filters/CommonFilters.ts

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1638,7 +1638,8 @@ function typeAliasMarkup(releases: MinecraftRelease[]) {
16381638
* Adds 'is_<type>' flags to APIs based on the type field.
16391639
*/
16401640
function typeFlags(releases: MinecraftRelease[]) {
1641-
const fixType = (typeJson: MinecraftType) => {
1641+
const fixType = (typeJson: MinecraftType, propertyName: string) => {
1642+
typeJson.is_void_return = typeJson.is_void_return ?? false;
16421643
typeJson.is_string = typeJson.is_string ?? false;
16431644
typeJson.is_undefined = typeJson.is_undefined ?? false;
16441645
typeJson.is_any = typeJson.is_any ?? false;
@@ -1657,7 +1658,11 @@ function typeFlags(releases: MinecraftRelease[]) {
16571658
if (typeJson.name === 'string') {
16581659
typeJson.is_string = true;
16591660
} else if (typeJson.name === 'undefined') {
1660-
typeJson.is_undefined = true;
1661+
if (propertyName === 'return_type') {
1662+
typeJson.is_void_return = true;
1663+
} else {
1664+
typeJson.is_undefined = true;
1665+
}
16611666
} else if (typeJson.name === 'any') {
16621667
typeJson.is_any = true;
16631668
} else if (typeJson.name === 'closure') {
@@ -1692,9 +1697,9 @@ function typeFlags(releases: MinecraftRelease[]) {
16921697
(jsonObject: Record<string, MinecraftType | MinecraftType[]>, propertyName: string) => {
16931698
const typeJson = jsonObject[propertyName];
16941699
if (Array.isArray(typeJson)) {
1695-
typeJson.forEach(fixType);
1700+
typeJson.forEach(t => fixType(t, propertyName));
16961701
} else {
1697-
fixType(typeJson);
1702+
fixType(typeJson, propertyName);
16981703
}
16991704
}
17001705
);

‎tools/api-docs-generator/src/modules/MinecraftScriptModule.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,7 @@ type MinecraftTypeHelper = {
208208

209209
// Runtime Markup
210210
original_name?: string;
211+
is_void_return?: boolean;
211212
is_string?: boolean;
212213
is_undefined?: boolean;
213214
is_any?: boolean;

‎tools/markup-generators-plugin/templates/msdocs/script/function.mustache

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,10 @@
2929
{{/arguments}}
3030
{{/arguments.length}}
3131
{{#return_type}}
32-
{{^is_undefined}}
32+
{{^is_void_return}}
3333

3434
**Returns** {{> type_with_links}}{{#is_optional}} | *undefined*{{/is_optional}}{{#returns_description_md}} - {{{returns_description_md}}}{{/returns_description_md}}
35-
{{/is_undefined}}
35+
{{/is_void_return}}
3636
{{#is_prerelease}}
3737

3838
> [!CAUTION]

‎tools/markup-generators-plugin/templates/msdocs/script/type_with_links.mustache

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{{#is_data_buffer}}{{#data_buffer_type}}[{{> type}}](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{{> type}}){{/data_buffer_type}}{{/is_data_buffer}}{{^is_data_buffer}}{{#is_generator}}Generator<{{#generator_type}}{{#yield_type}}{{> type_with_links}}{{/yield_type}}, {{#return_type}}{{> type_with_links}}{{/return_type}}, {{#next_type}}{{> type_with_links}}{{/next_type}}{{/generator_type}}>{{/is_generator}}{{^is_generator}}{{#is_map}}Record<{{#key_type}}{{> type_with_links}}{{/key_type}}, {{#value_type}}{{> type_with_links}}{{/value_type}}>{{/is_map}}{{^is_map}}{{#is_iterator_result}}IteratorResult&lt;{{#iterator_type}}{{> type_with_links}}{{/iterator_type}}&gt;{{/is_iterator_result}}{{^is_iterator_result}}{{#is_iterator}}Iterator&lt;{{#iterator_type}}{{> type_with_links}}{{/iterator_type}}&gt;{{/is_iterator}}{{^is_iterator}}{{#is_optional_type}}{{#optional_type}}{{> type_with_links}}{{/optional_type}}{{/is_optional_type}}{{^is_optional_type}}{{#is_variant}}{{#variant_types}}{{> type_with_links}}{{^is_last}} | {{/is_last}}{{/variant_types}}{{/is_variant}}{{^is_variant}}{{#is_promise}}Promise&lt;{{#promise_type}}{{> type_with_links}}{{/promise_type}}&gt;{{/is_promise}}{{^is_promise}}{{#is_array}}{{#element_type}}{{#is_optional_type}}{{#optional_type}}({{/optional_type}}{{/is_optional_type}}{{#is_variant}}({{/is_variant}}{{> type_with_links}}{{#is_optional_type}}{{#optional_type}} | *undefined*){{/optional_type}}{{/is_optional_type}}{{#is_variant}}){{/is_variant}}[]{{/element_type}}{{/is_array}}{{^is_array}}{{#is_undefined}}*void*{{/is_undefined}}{{^is_undefined}}{{#is_closure}}{{#closure_type}}({{#argument_types}}arg{{index}}: {{> type_with_links}}{{^is_last}}, {{/is_last}}{{/argument_types}}) => {{#return_type}}{{#is_variant}}({{/is_variant}}{{> type_with_links}}{{#is_variant}}){{/is_variant}}{{/return_type}}{{/closure_type}}{{^closure_type}}() => void{{/closure_type}}{{/is_closure}}{{^is_closure}}{{#argument_valid_values.length}}{{#argument_valid_values}}`'{{argument_valid_value}}'`{{^argument_valid_value_end}}, {{/argument_valid_value_end}}{{/argument_valid_values}}{{/argument_valid_values.length}}{{^argument_valid_values}}{{#is_bind_type}}[{{/is_bind_type}}*{{#from_module.is_external_module}}{{{from_module.name}}}.{{/from_module.is_external_module}}{{{name}}}*{{#is_bind_type}}]({{#from_module.is_external_module}}../../../{{{from_module.folder_path}}}/{{{from_module.filepath_name}}}/{{/from_module.is_external_module}}{{{name}}}.md){{/is_bind_type}}{{/argument_valid_values}}{{/is_closure}}{{/is_undefined}}{{/is_array}}{{/is_promise}}{{/is_variant}}{{/is_optional_type}}{{/is_iterator}}{{/is_iterator_result}}{{/is_map}}{{/is_generator}}{{/is_data_buffer}}
1+
{{#is_void_return}}*void*{{/is_void_return}}{{^is_void_return}}{{#is_data_buffer}}{{#data_buffer_type}}[{{> type}}](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{{> type}}){{/data_buffer_type}}{{/is_data_buffer}}{{^is_data_buffer}}{{#is_generator}}Generator<{{#generator_type}}{{#yield_type}}{{> type_with_links}}{{/yield_type}}, {{#return_type}}{{> type_with_links}}{{/return_type}}, {{#next_type}}{{> type_with_links}}{{/next_type}}{{/generator_type}}>{{/is_generator}}{{^is_generator}}{{#is_map}}Record<{{#key_type}}{{> type_with_links}}{{/key_type}}, {{#value_type}}{{> type_with_links}}{{/value_type}}>{{/is_map}}{{^is_map}}{{#is_iterator_result}}IteratorResult&lt;{{#iterator_type}}{{> type_with_links}}{{/iterator_type}}&gt;{{/is_iterator_result}}{{^is_iterator_result}}{{#is_iterator}}Iterator&lt;{{#iterator_type}}{{> type_with_links}}{{/iterator_type}}&gt;{{/is_iterator}}{{^is_iterator}}{{#is_optional_type}}{{#optional_type}}{{> type_with_links}}{{/optional_type}}{{/is_optional_type}}{{^is_optional_type}}{{#is_variant}}{{#variant_types}}{{> type_with_links}}{{^is_last}} | {{/is_last}}{{/variant_types}}{{/is_variant}}{{^is_variant}}{{#is_promise}}Promise&lt;{{#promise_type}}{{> type_with_links}}{{/promise_type}}&gt;{{/is_promise}}{{^is_promise}}{{#is_array}}{{#element_type}}{{#is_optional_type}}{{#optional_type}}({{/optional_type}}{{/is_optional_type}}{{#is_variant}}({{/is_variant}}{{> type_with_links}}{{#is_optional_type}}{{#optional_type}} | *undefined*){{/optional_type}}{{/is_optional_type}}{{#is_variant}}){{/is_variant}}[]{{/element_type}}{{/is_array}}{{^is_array}}{{#is_undefined}}*undefined*{{/is_undefined}}{{^is_undefined}}{{#is_closure}}{{#closure_type}}({{#argument_types}}arg{{index}}: {{> type_with_links}}{{^is_last}}, {{/is_last}}{{/argument_types}}) => {{#return_type}}{{#is_variant}}({{/is_variant}}{{> type_with_links}}{{#is_variant}}){{/is_variant}}{{/return_type}}{{/closure_type}}{{^closure_type}}() => void{{/closure_type}}{{/is_closure}}{{^is_closure}}{{#argument_valid_values.length}}{{#argument_valid_values}}`'{{argument_valid_value}}'`{{^argument_valid_value_end}}, {{/argument_valid_value_end}}{{/argument_valid_values}}{{/argument_valid_values.length}}{{^argument_valid_values}}{{#is_bind_type}}[{{/is_bind_type}}*{{#from_module.is_external_module}}{{{from_module.name}}}.{{/from_module.is_external_module}}{{{name}}}*{{#is_bind_type}}]({{#from_module.is_external_module}}../../../{{{from_module.folder_path}}}/{{{from_module.filepath_name}}}/{{/from_module.is_external_module}}{{{name}}}.md){{/is_bind_type}}{{/argument_valid_values}}{{/is_closure}}{{/is_undefined}}{{/is_array}}{{/is_promise}}{{/is_variant}}{{/is_optional_type}}{{/is_iterator}}{{/is_iterator_result}}{{/is_map}}{{/is_generator}}{{/is_data_buffer}}{{/is_void_return}}

‎tools/markup-generators-plugin/templates/tsdef/type.mustache

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{{#is_data_buffer}}{{#data_buffer_type}}{{> type}}{{/data_buffer_type}}{{/is_data_buffer}}{{^is_data_buffer}}{{#is_generator}}Generator<{{#generator_type}}{{#yield_type}}{{> type}}{{/yield_type}}, {{#return_type}}{{> type}}{{/return_type}}, {{#next_type}}{{> type}}{{/next_type}}{{/generator_type}}>{{/is_generator}}{{^is_generator}}{{#is_map}}Record<{{#key_type}}{{> type}}{{/key_type}}, {{#value_type}}{{> type}}{{/value_type}}>{{/is_map}}{{^is_map}}{{#is_iterator_result}}IteratorResult<{{#iterator_type}}{{> type}}{{/iterator_type}}>{{/is_iterator_result}}{{^is_iterator_result}}{{#is_iterator}}Iterator<{{#iterator_type}}{{> type}}{{/iterator_type}}>{{/is_iterator}}{{^is_iterator}}{{#is_optional_type}}{{#optional_type}}{{> type}}{{/optional_type}}{{/is_optional_type}}{{^is_optional_type}}{{#is_variant}}{{#variant_types}}{{> type}}{{^is_last}} | {{/is_last}}{{/variant_types}}{{/is_variant}}{{^is_variant}}{{#is_promise}}Promise<{{#promise_type}}{{> type}}{{/promise_type}}>{{/is_promise}}{{^is_promise}}{{#is_any}}any{{/is_any}}{{^is_any}}{{#is_array}}{{#element_type}}{{#is_optional_type}}{{#optional_type}}({{/optional_type}}{{/is_optional_type}}{{#is_variant}}({{/is_variant}}{{> type}}{{#is_optional_type}}{{#optional_type}} | undefined){{/optional_type}}{{/is_optional_type}}{{#is_variant}}){{/is_variant}}{{/element_type}}[]{{/is_array}}{{^is_array}}{{#is_closure}}{{#closure_type}}({{#argument_types}}arg{{index}}: {{> type}}{{^is_last}}, {{/is_last}}{{/argument_types}}) => {{#return_type}}{{#is_variant}}({{/is_variant}}{{> type}}{{#is_variant}}){{/is_variant}}{{/return_type}}{{/closure_type}}{{^closure_type}}() => void{{/closure_type}}{{/is_closure}}{{^is_closure}}{{#argument_valid_values.length}}({{#argument_valid_values}}'{{argument_valid_value}}'{{^argument_valid_value_end}}|{{/argument_valid_value_end}}{{/argument_valid_values}}){{/argument_valid_values.length}}{{^argument_valid_values}}{{#is_undefined}}void{{/is_undefined}}{{^is_undefined}}{{#from_module.is_external_module}}{{from_module.variable_name}}.{{/from_module.is_external_module}}{{{name}}}{{/is_undefined}}{{/argument_valid_values}}{{/is_closure}}{{/is_array}}{{/is_any}}{{/is_promise}}{{/is_variant}}{{/is_optional_type}}{{/is_iterator}}{{/is_iterator_result}}{{/is_map}}{{/is_generator}}{{/is_data_buffer}}
1+
{{#is_void_return}}void{{/is_void_return}}{{^is_void_return}}{{#is_data_buffer}}{{#data_buffer_type}}{{> type}}{{/data_buffer_type}}{{/is_data_buffer}}{{^is_data_buffer}}{{#is_generator}}Generator<{{#generator_type}}{{#yield_type}}{{> type}}{{/yield_type}}, {{#return_type}}{{> type}}{{/return_type}}, {{#next_type}}{{> type}}{{/next_type}}{{/generator_type}}>{{/is_generator}}{{^is_generator}}{{#is_map}}Record<{{#key_type}}{{> type}}{{/key_type}}, {{#value_type}}{{> type}}{{/value_type}}>{{/is_map}}{{^is_map}}{{#is_iterator_result}}IteratorResult<{{#iterator_type}}{{> type}}{{/iterator_type}}>{{/is_iterator_result}}{{^is_iterator_result}}{{#is_iterator}}Iterator<{{#iterator_type}}{{> type}}{{/iterator_type}}>{{/is_iterator}}{{^is_iterator}}{{#is_optional_type}}{{#optional_type}}{{> type}}{{/optional_type}}{{/is_optional_type}}{{^is_optional_type}}{{#is_variant}}{{#variant_types}}{{> type}}{{^is_last}} | {{/is_last}}{{/variant_types}}{{/is_variant}}{{^is_variant}}{{#is_promise}}Promise<{{#promise_type}}{{> type}}{{/promise_type}}>{{/is_promise}}{{^is_promise}}{{#is_any}}any{{/is_any}}{{^is_any}}{{#is_array}}{{#element_type}}{{#is_optional_type}}{{#optional_type}}({{/optional_type}}{{/is_optional_type}}{{#is_variant}}({{/is_variant}}{{> type}}{{#is_optional_type}}{{#optional_type}} | undefined){{/optional_type}}{{/is_optional_type}}{{#is_variant}}){{/is_variant}}{{/element_type}}[]{{/is_array}}{{^is_array}}{{#is_closure}}{{#closure_type}}({{#argument_types}}arg{{index}}: {{> type}}{{^is_last}}, {{/is_last}}{{/argument_types}}) => {{#return_type}}{{#is_variant}}({{/is_variant}}{{> type}}{{#is_variant}}){{/is_variant}}{{/return_type}}{{/closure_type}}{{^closure_type}}() => void{{/closure_type}}{{/is_closure}}{{^is_closure}}{{#argument_valid_values.length}}({{#argument_valid_values}}'{{argument_valid_value}}'{{^argument_valid_value_end}}|{{/argument_valid_value_end}}{{/argument_valid_values}}){{/argument_valid_values.length}}{{^argument_valid_values}}{{#is_undefined}}undefined{{/is_undefined}}{{^is_undefined}}{{#from_module.is_external_module}}{{from_module.variable_name}}.{{/from_module.is_external_module}}{{{name}}}{{/is_undefined}}{{/argument_valid_values}}{{/is_closure}}{{/is_array}}{{/is_any}}{{/is_promise}}{{/is_variant}}{{/is_optional_type}}{{/is_iterator}}{{/is_iterator_result}}{{/is_map}}{{/is_generator}}{{/is_data_buffer}}{{/is_void_return}}

0 commit comments

Comments
 (0)