CesiumGS / CesiumGS/cesium

Use `@namespace` in addition to `@enum` for jsdoc

Open
#10,259 3 comments 0 reactions 0 assignees View on GitHub
category - doc type - cleanup
Dominant language
JavaScript
Stars
15.7k
Forks
3.9k
Avg merge
4d 6h
Merged PRs (30d)
34

Description

## Old
When using the `@enum` tag by itself it puts the documentation in the global section and omits static functions on the enum. It's cluttered and missing information.

![Screenshot from 2022-04-01 10-49-15](https://user-images.githubusercontent.com/1328450/161287872-fd6e0139-c345-4fa2-a259-ba1e69517ae1.png)

## New
By adding the `@namespace` tag it creates a new page for the enum and show the static functions:
![Screenshot from 2022-04-01 10-49-37](https://user-images.githubusercontent.com/1328450/161288425-a45a8955-2977-469f-9220-5a51f95475a1.png)

---

Here's how the fix would look for `VoxelShapeType`:
```
/**
* An enum of voxel shapes supported by EXT_primitive_voxels. The shape controls
* how the voxel grid is mapped to 3D space.
*
* @namespace
* @enum VoxelShapeType
*/
```

One way to go about fixing this for all enums is to:
- Run `npm run generateDocumentation`
- Go to `http://localhost:8080/Build/Documentation/global.html`
- Add `@namespace` to every enum until there are no more in the global section

Also, update https://github.com/CesiumGS/cesium/tree/main/Documentation/Contributors/DocumentationGuide with information about enums / namespace.

Contributor guide

Open the contributing guide

Research direction

Run `npm run generateDocumentation` and inspect `http://localhost:8080/Build/Documentation/global.html` to identify enums still documented in the global section. Add `@namespace` to those enum comments, then update `Documentation/Contributors/DocumentationGuide` with the enum and namespace guidance. Done means the enums have dedicated documentation pages with their static functions shown.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.