# Understanding JSDoc Annotations in MakeCode (Part 1)
**URL:** https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411
**Category:** Help
**Tags:** javascript, tutorial, extension, make, demo
**Created:** [August 15, 2026, 7:57pm UTC](https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411 "2026-08-15T19:57:32Z")
**Posts on this page:** 6
**Page:** 1
### Author:  [@CodaKnight](https://forum.makecode.com/u/CodaKnight)
#### Post date: [August 15, 2026, 7:57pm UTC](https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411/1 "2026-08-15T19:57:32Z")
# 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:
```typescript
/**
* 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.
1. `@returns` / `@return` — describes the returned value
2. `@example` — provides an example of usage
3. `@description` — provides a longer description
4. `@summary` — provides a short summary
5. `@throws` / `@exception` — documents errors an API may throw
6. `@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:**
```typescript
/**
* 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:**
```typescript
/**
* 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:**
```typescript
/**
* 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:**
```typescript
/**
* 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:
```typescript
/**
* @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:**
```typescript
/**
* 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.
---
### Author:  [@VoxelMaster64](https://forum.makecode.com/u/VoxelMaster64)
#### Post date: [August 16, 2026, 6:45pm UTC](https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411/2 "2026-08-16T18:45:31Z")
please continue, I never knew about many of those
---
### Author:  [@CodaKnight](https://forum.makecode.com/u/CodaKnight)
#### Post date: [August 23, 2026, 7:22pm UTC](https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411/3 "2026-08-23T19:22:00Z")
Alright day 2 of the JSDoc Annotations:
# Part 2: API Metadata
These provide additional information about an API.
- `@version` — specifies the version associated with an API
- `@since` — indicates when an API was introduced
- `@see` — points to related documentation or another API
- `@author` — identifies the author
- `@license` — specifies licensing information
- `@copyright` — provides copyright information
* * *
### **`@version`**
#### **What it does:**
Specifies the version of a block, namespace, etc. I usually use it for the namespace/extension and then use **`@since`** for the blocks.
**Where it can be used:**
Inside a JSDoc comment (`/**... */`) above a function, method, or other callable API that has parameters.
**Example:**
```typescript
/**
* @version 0.0.1
*/
namespace myCoolExtension {
// ...
}
```
**Notes:**
Usually just an API/styling annotation rather than actually giving useful information.
* * *
### **`@since`**
#### **What it does:**
Describes the block, method, etc. as what version it was included.
**Where it can be used:**
Inside a JSDoc comment (`/**... */`) above a function, method, or other callable API that has parameters.
**Example:**
```typescript
/**
* Sets the player's health.
* @param player The player whose health will be changed.
* @param health The new health value.
* @since 0.0.1
*/
export function setHealth(player: Sprite, health: number) {
// ...
}
```
**Notes:**
Similar to the @version annotation, I usually use @since for the blocks and @version for the/a namespace.
* * *
### **`@see`**
#### **What it does:**
Gives information of blocks to look at. Usually used for related methods, blocks etc. with the block, method, etc. with the annotation.
**Where it can be used:**
Inside a JSDoc comment (`/**... */`) above a function, method, or other callable API that has parameters.
**Example:**
```typescript
/**
* Sets the player's health.
* @param player The player whose health will be changed.
* @param health The new health value.
* @see removeHealth
*/
export function setHealth(player: Sprite, health: number) {
// ...
}
```
**Notes:**
If you plan to use this for your extension’s blocks, you should use the function name instead of the block name. You don’t need to but it makes much more sense.
Example
```typescript
/**
* Sets the player's health.
* @param player The player whose health will be changed.
* @param health The new health value.
* @see negativeInfinity (GOOD)
*/
export function positiveInfinity(): number {
return Infinity
}
/**
* Sets the player's health.
* @param player The player whose health will be changed.
* @param health The new health value.
* @see positive infinity (BAD)
*/
export function negativeInfinity(): number {
return -Infinity
}
```
* * *
### `@author`
**What it does:**
Identifies the person or people who created or contributed to a piece of code, such as a function, class, or extension.
**Where it can be used:**
Inside a JSDoc comment (`/**... */`) above the API or code being documented.
**Example:**
```typescript
/**
* Adds two numbers together.
* @param a The first number.
* @param b The second number.
* @returns The sum of the two numbers.
* @author Alex
*/
export function add(a: number, b: number): number {
return a + b
}
```
**Notes:**
`@author` is primarily **documentation metadata**. It doesn’t change how the code works. You can also use it to credit multiple contributors if appropriate.
For an extension, you could also put it on the main namespace or class:
```typescript
/**
* Additional math utilities for MakeCode Arcade.
* @author CodaKnight
*/
namespace MathX {
// ...
}
```
* * *
### `@license`
**What it does:**
Specifies the **license under which the code is released**. It tells users what they are allowed to do with the code, such as whether they can modify, distribute, or use it in other projects.
**Where it can be used:**
Inside a JSDoc comment (`/**... */`) above a function, class, namespace, or other piece of code. It can also be used in documentation for an entire project or extension.
**Example:**
```typescript
/**
* Adds two numbers together.
* @param a The first number.
* @param b The second number.
* @returns The sum of the two numbers.
* @license MIT
*/
export function add(a: number, b: number): number {
return a + b
}
```
**Notes:**
`@license` is **documentation metadata**. It does not actually apply a license to your code by itself. The project’s actual license should normally be included in a `LICENSE` file or another appropriate location.
For example, if your extension is released under the MIT License, you might document it with `@license MIT`.
* * *
### `@copyright`
**What it does:**
Identifies the copyright holder and can provide a copyright notice for the code being documented.
**Where it can be used:**
Inside a JSDoc comment (`/**... */`) above a function, class, namespace, or other piece of code. It can also be used for an entire project or extension.
**Example:**
```typescript
/**
* Adds two numbers together.
* @param a The first number.
* @param b The second number.
* @returns The sum of the two numbers.
* @copyright 2026 Alex
*/
export function add(a: number, b: number): number {
return a + b
}
```
**Notes:**
`@copyright` is **documentation metadata**. It does not create or establish copyright protection by itself. Copyright generally exists automatically when an original work is created.
For an extension, you might instead put the copyright notice near the top of the main source file:
```typescript
/**
* MathX - Additional mathematical utilities for MakeCode Arcade.
*
* @copyright 2026 CodaKnight
* @license MIT
*/
```
That makes the copyright and license information easy to find for the entire extension.
---
### Author:  [@VoxelMaster64](https://forum.makecode.com/u/VoxelMaster64)
#### Post date: [August 24, 2026, 9:49pm UTC](https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411/4 "2026-08-24T21:49:16Z")
what about @body? i found it in game.onUpdate:
```typescript
/**
* Update the position and velocities of sprites
* @param body code to execute
*/
//% group="Gameplay"
//% help=game/on-update weight=100 afterOnStart=true
//% blockId=gameupdate block="on game update"
//% blockAllowMultiple=1
export function onUpdate(a: () => void): void {
if (!a) return;
game.eventContext().registerFrameHandler(scene.UPDATE_PRIORITY, a);
}
```
---
### Author:  [@TheEarth](https://forum.makecode.com/u/TheEarth)
#### Post date: [August 24, 2026, 11:03pm UTC](https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411/5 "2026-08-24T23:03:38Z")
maybe its to make a container block
---
### Author:  [@CodaKnight](https://forum.makecode.com/u/CodaKnight)
#### Post date: [August 25, 2026, 11:48pm UTC](https://forum.makecode.com/t/understanding-jsdoc-annotations-in-makecode-part-1/45411/6 "2026-08-25T23:48:13Z")
`@body` isn’t actually a JSDoc annotation. It’s just `@param` with `body` specified as the parameter name. In this example, the function’s actual parameter is `a`, so `@param body` doesn’t match the current parameter name. It would normally be written as:
```typescript
/**
* Update the position and velocities of sprites
* @param a code to execute
*/
```
But also, I think another reason they would do that is because it makes much more since if you have **body** instead of **a:**
```typescript
/**
* Update the position and velocities of sprites
* @param body code to execute
*/
```
then:
```typescript
/**
* Update the position and velocities of sprites
* @param a code to execute
*/
```