WARNING: Lot’s of text in these 5 posts:
MakeCode-Specific* annotations will be in part 5 of this post. Please ask questions after reading both posts unless about a specific part of the posts.
Hey guys! While working on my extensions and learning more about JSDoc annotations and *MakeCode-specific //% annotations, I wanted to make a reference explaining what they are and what they do. I don’t think a lot of people who make extensions know about all of these annotations besides things like @param, so I thought it would be useful to put them all in one place.
If I made a mistake somewhere, missed an annotation, or you have something you’d like to clarify or add, feel free to reply!
Understanding JSDoc Annotations
When working with TypeScript in MakeCode Arcade, you may come across annotations such as @param, @returns, @deprecated, and MakeCode-specific //% annotations.
These annotations provide metadata about your code. They can describe what a function, class, property, or parameter does and can be used by documentation generators, editors, and other tools to provide additional information about your code.
This post is a reference for some of the JSDoc annotations you may encounter when developing MakeCode extensions.
JSDoc Annotations
This guide organizes the annotations into categories and explains what each one does, where it can be used, and how it affects your extension.
Understanding JSDoc & MakeCode Annotations
When working with TypeScript in MakeCode Arcade, you may come across two different kinds of annotations:
- JSDoc annotations, such as
@param,@returns, and@deprecated - MakeCode-specific annotations, which use the
//%syntax
These annotations provide metadata about your code. They can describe functions, classes, parameters, properties, blocks, events, and other parts of an extension.
Some annotations are used primarily for documentation, while MakeCode-specific annotations can control how your extension appears and behaves in the MakeCode editor.
This post is a reference for some of the annotations you may encounter when developing MakeCode extensions.
JSDoc Annotations
JSDoc annotations are written inside documentation comments using the @ symbol:
/**
* Adds two numbers together.
* @param a The first number.
* @param b The second number.
* @returns The sum of the two numbers.
*/
function add(a: number, b: number): number {
return a + b
}
This section covers the JSDoc annotations that are useful when creating MakeCode extensions.
Documentation & Description
These explain what an API does and how to use it.
@returns/@return— describes the returned value@example— provides an example of usage@description— provides a longer description@summary— provides a short summary@throws/@exception— documents errors an API may throw@param— describes a parameter
@param
What it does:
Describes a parameter that is passed into a function. It lets you explain what the parameter represents and what it is used for.
Where it can be used:
Inside a JSDoc comment (/** ... */) above a function, method, or other callable API that has parameters.
Example:
/**
* Sets the player's health.
* @param player The player whose health will be changed.
* @param health The new health value.
*/
export function setHealth(player: Sprite, health: number) {
// ...
}
Result:
The @param annotation documents both parameters:
player— The player whose health will be changed.health— The new health value.
Notes:
The parameter name after @param should match the actual parameter name in the function. @param only provides documentation; it doesn’t change how the parameter works.
@returns
What it does:
Describes the value that a function or method returns after it finishes running.
Where it can be used:
Inside a JSDoc comment (/** ... */) above a function or method that returns a value.
Example:
/**
* Adds two numbers together.
* @param a The first number.
* @param b The second number.
* @returns The sum of the two numbers.
*/
export function add(a: number, b: number): number {
return a + b
}
Notes:
@returns is only useful when the function actually returns a value. If a function has a void return type, you generally don’t need to use it.
You may also see @return instead of @returns; both are commonly recognized as the same JSDoc tag.
@example
What it does:
Provides an example showing how to use a function, class, method, or other API. This can make your documentation easier to understand by showing the API in a real piece of code.
Where it can be used:
Inside a JSDoc comment (/** ... */) above the function, method, class, or API you are documenting.
Example:
/**
* Adds two numbers together.
* @param a The first number.
* @param b The second number.
* @returns The sum of the two numbers.
* @example
* let result = add(5, 3)
* console.log(result)
*/
export function add(a: number, b: number): number {
return a + b
}
Notes:
@example can be especially useful for extension APIs because it shows users how the API is intended to be used, rather than only explaining what it does. You can include more than one @example if there are multiple useful ways to use something.
@deprecated
What it does:
Marks a function, class, property, or other API as deprecated, meaning it is outdated or no longer recommended for use. It lets users know that they should use a newer or preferred alternative instead.
Where it can be used:
Inside a JSDoc comment (/** ... */) above the API that you want to mark as deprecated.
Example:
/**
* Gets the player's old score.
* @deprecated Use `getScore()` instead.
*/
export function getOldScore(): number {
return 0
}
/**
* Gets the player's current score.
*/
export function getScore(): number {
return 0
}
Notes:
@deprecated doesn’t remove or disable the API. It simply tells documentation tools, editors, and users that the API should generally no longer be used.
You can also include why something was deprecated:
/**
* @deprecated This function has been replaced by `getScore()`.
*/
@throws
What it does:
Describes an error or exception that a function can throw while it is running. It can explain what causes the error and what kind of error may occur.
Where it can be used:
Inside a JSDoc comment (/** ... */) above a function or method that can throw an error.
Example:
/**
* Gets an item from an array.
* @param items The array to search.
* @param index The index of the item.
* @returns The item at the specified index.
* @throws Error if the index is outside the array.
*/
export function getItem(items: string[], index: number): string {
if (index < 0 || index >= items.length) {
throw "Index out of range"
}
return items[index]
}
Notes:
@throws is documentation only. It doesn’t cause an error to be thrown or change how the function handles errors.
You may also see @exception, which is another name commonly used for the same JSDoc concept.