JSDoc Conventions

Oidis uses a minimal, IntelliSense-focused JSDoc style. The goal is to provide useful hover information in IDEs without cluttering the codebase with verbose documentation blocks.

Documentation Philosophy

Every piece of documentation — JSDoc, inline comments, class descriptions — must add value. If it restates what the code already says, it is noise and should not exist.

Core principles:

• Code must be self-explanatory. Write clean, well-named code that does not need commenting. JSDoc exists for IntelliSense/DX, not as a substitute for readable code.
• Never restate what code already says. A JSDoc like @returns {string} Returns the name. on getName() adds zero value. A comment like // increment counter above counter++ is worse than no comment.
• Inline comments are rare. Only add them when a piece of logic is genuinely non-obvious — complex algorithms, non-intuitive business rules, or intentional workarounds. If you feel the need to comment, first consider whether the code itself can be made clearer.
• Private and protected methods need no documentation. They are internal implementation details. If they are complex enough to need explanation, simplify the code or add a targeted inline comment on the complex part.
• Less is more. A codebase with minimal, high-value documentation is better than one full of redundant comments that developers learn to ignore.

When JSDoc is Required

JSDoc comments are required on:

• All public methods on exported classes
• All exported standalone functions
• All public static methods

These are the entry points that other developers interact with. Accurate JSDoc on public APIs ensures that consumers get meaningful autocomplete and hover information.

When JSDoc is NOT Required

JSDoc may be omitted on:

• Private and protected methods — internal implementation details
• Interface method signatures — the implementing class provides JSDoc
• Constructor methods — unless the constructor has non-obvious parameters
• Simple toString() overrides — especially those that just delegate to ToString()
• Getter/setter pairs where the JSDoc would be purely redundant (e.g., getName() on a property named Name)

Approved Tags

Only three tags are permitted in Oidis JSDoc:

Tag	Usage
@param	Document each parameter
@returns	Document the return value
@deprecated	Mark API scheduled for removal

Do NOT use any of the following tags:

• @throws / @exception
• @example
• @see
• @since
• @author
• @todo
• @type

Format Rules

@param Format

@param {Type} $name Description.

• Type in curly braces: {string}, {number}, {boolean}, {any}, etc.
• Parameter name with $ prefix, matching the Oidis naming convention
• Description starts with a capital letter and ends with a period
• Use {any} for untyped parameters
• Use {string | number} for union types (spaces around the pipe)
• Use {any[]} or {string[]} for array types

@returns Format

@returns {Type} Returns ...

• Always starts with the word "Returns"
• Capital R, followed by the description of what is returned
• Ends with a period
• For void methods: @returns {void} (no description text needed)

@deprecated Format

@deprecated Reason or migration hint.

• Place @deprecated as the first tag in the JSDoc block, before @param and @returns
• Follow with a brief reason or pointer to the replacement API
• IDEs (IntelliJ, VS Code) render deprecated members with strikethrough, giving an immediate visual signal that the API should be avoided
• For wiki documentation, complement @deprecated with a :::warning admonition on the relevant page so that readers who browse the docs (not just the code) are also informed

/**
 * @deprecated Use StringUtils.Format() instead. Will be removed in v2027.1.0.
 * @param {string} $template Template string.
 * @param {any[]} $args Replacement values.
 * @returns {string} Returns the formatted string.
 */
public static FormatLegacy($template : string, ...$args : any[]) : string {

Class-Level JSDoc

• Do NOT add class-level JSDoc unless the class purpose is non-obvious from its name
• Most Oidis classes follow clear naming (e.g., OrderRecord, UsersPanelController) that makes class-level JSDoc redundant
• If present, class-level JSDoc should be a single sentence, no tags
• Wrap long descriptions to stay within the 140-character line limit

Do NOT add class-level JSDoc to:

• Enums — member names are self-documenting
• Simple interfaces (IButton, ILabel, ICheckBox) — the name says everything
• Event handler interfaces (IButtonEvents, IMouseEventsHandler)
• Event args classes (MouseEventArgs, ResizeEventArgs)
• Error pages, test classes, and other classes with descriptive names

Class-level JSDoc is appropriate for:

• Abstract base classes where the name alone does not explain the concept (e.g., BasePropagableEnum)
• Core framework interfaces with broad, non-obvious scope (e.g., IGuiCommons, IGuiElement)
• Protocol/data structure interfaces where the structure is not evident from the name

General Formatting

• Use /** and */ delimiters (standard JSDoc block)
• Each tag on its own line, prefixed with *
• No blank lines between tags
• No alignment padding between tag columns — just single spaces

Examples

Good

/**
 * @param {string} $message Log message with format placeholders.
 * @param {any[]} $parameters Format parameters.
 * @returns {void}
 */
public Info($message : string, ...$parameters : any[]) : void {

/**
 * @param {string} $key Property key to look up.
 * @returns {T | undefined} Returns the value associated with the key, or undefined if not found.
 */
public Get($key : string) : T | undefined {

/**
 * @param {IPropertyOptions} $options Property configuration options.
 * @returns {PropertyDecorator} Returns the decorator function.
 */
public static Property($options : IPropertyOptions) : PropertyDecorator {

/**
 * @param {string | number} $value Value to convert.
 * @param {boolean} $strict Enable strict mode validation.
 * @returns {string} Returns the converted string representation.
 */
public static ToString($value : string | number, $strict : boolean = false) : string {

Bad

// BAD: verbose description line, missing $ prefix, wrong @returns format
/**
 * Logs an informational message to all adapters.
 * @param message - the message
 * @returns nothing
 */

// BAD: using @throws and @example (not approved tags)
/**
 * @param {string} $key The key.
 * @returns {T} Returns the value.
 * @throws {Error} If key is not found.
 * @example
 * list.Get("myKey");
 */

// BAD: lowercase description start, missing period, no type in braces
/**
 * @param $name name of the entity
 * @returns the entity name as string
 */

// BAD: using dash separator after param name (TSDoc style, not JSDoc)
/**
 * @param {string} $name - The entity name.
 * @returns {string} Returns the name.
 */

No-JSDoc Methods

Certain methods are acceptable without JSDoc:

• toString() overrides that simply delegate to the framework ToString() method. These are native JS overrides and their purpose is self-evident.
• Getter/setter pairs where the method name already fully describes the operation (e.g., getName() / setName() on a class with a Name property). Adding JSDoc like @returns {string} Returns the name. provides zero additional value.
• Event handler callbacks registered internally (e.g., private onButtonClick()) — these are private and exempt from JSDoc anyway.

When in doubt, add the JSDoc. It is better to have slightly redundant documentation than to leave a public method undocumented.

Enforcement

The following ESLint eslint-plugin-jsdoc rules are recommended for Oidis projects and could be configured to enforce these conventions:

Rule	Purpose
jsdoc/check-param-names	Ensures @param names match function signature
jsdoc/require-param-description	Requires description text for every @param
jsdoc/require-returns-description	Requires description text for @returns
jsdoc/check-tag-names	Restricts to approved tags only
jsdoc/require-param-type	Ensures {Type} is present on @param
jsdoc/require-returns-type	Ensures {Type} is present on @returns

note

These rules are not currently enforced automatically in the Oidis build pipeline. JSDoc quality is maintained through code review and the conventions documented on this page. Future versions of Oidis Builder may integrate these checks.

---

See also: Naming Conventions | TypeScript Formatting | Coding Standards