Skip to content

Docstring Guidelines

This document defines standards for writing docstrings in the gaslamp project.

Docstrings are used to generate API documentation via TypeDoc and help developers understand code intent at a glance.

Quick Standard Template

Every exported function, class, and interface should follow this pattern:

TypeScript
/**
 * One-line summary of what this does.
 *
 * Optional extra explanation here if needed.
 *
 * @param paramName Description of parameter
 * @returns Description of return value
 *
 * @example
 * ```javascript
 * const df = gaslamp.BareFrame.fromSheet(sheet);
 * const result = df.filter(row => row.get('age') >= 18);
 * ```
 *
 * @category DataFrame
 */

Essential Rules

1. Use TypeDoc Format

Use /** ... */ block comments with @ tags. Do not use JSDoc-only tags like @typedef or @callback.

2. One-Line Summary (Required)

A single sentence describing what the symbol does, in present tense.

TypeScript
/** Filters rows where a column value matches a condition. */

Not:

  • ✗ "Filter rows" (incomplete sentence)
  • ✗ "Used to filter rows" (passive voice)

3. Parameters (@param)

Describe what each parameter does. Do not repeat the type (TypeScript already shows it).

TypeScript
/**
 * @param predicate Function that returns true for rows to keep
 * @param options Optional configuration (default: {})
 */

4. Return Value (@returns)

Describe what the caller receives. Omit only if the function returns void.

TypeScript
/**
 * @returns A new BareFrame with only matching rows
 */

Show the most common use case in a code block.

Always use javascript language identifier and gaslamp. prefix:

TypeScript
/**
 * @example
 * ```javascript
 * const df = gaslamp.BareFrame.fromSheet(sheet);
 * const adults = df.filter(row => row.get('age') >= 18);
 * ```
 */

Why:

  • javascript makes examples copy-paste executable in Google Apps Script
  • gaslamp. prefix is required since GAS doesn't support ES modules

6. Category (@category)

Required for exported symbols. Choose one:

  • DataFrame — BareFrame, GroupedFrame, operations
  • FlameFrame — Validation gates
  • Flame — FlameGuards, FlameWright type validation
  • Expression — Expression builders and predicates
  • Convert — Data conversion utilities
  • Logger — AfterGlow logging
  • Gaslets — Google Apps Script utilities
  • Gears — General utilities
  • JestLite — Testing framework

7. Extra Sections (Optional)

Use @remarks for important context:

TypeScript
/**
 * Filters rows where a column value matches a condition.
 *
 * @remarks
 * This uses eager evaluation (applied immediately).
 * For deferred evaluation with optimizations, use LazyFrame.
 */

Use @since for version information:

TypeScript
/**
 * @since 0.62.0
 */

Use @deprecated when removing features:

TypeScript
/**
 * @deprecated Use BareFrame.filter() instead.
 */

Complete Examples

Function

TypeScript
/**
 * Filters rows where a column value matches a condition.
 *
 * This method applies the filter immediately (eager evaluation).
 *
 * @param predicate Function that returns true for rows to keep
 * @returns A new BareFrame with only matching rows
 *
 * @example
 * ```javascript
 * const df = gaslamp.BareFrame.fromSheet(sheet);
 * const adults = df.filter(row => row.get('age') >= 18);
 * ```
 *
 * @category DataFrame
 * @since 0.60.0
 */
public filter(predicate: (row: Map<string, Cell>) => boolean): BareFrame {
  // implementation
}

Class

TypeScript
/**
 * A tabular data structure with column-oriented access.
 *
 * BareFrame is the primary way to read, transform, and write data in gaslamp.
 * All filtering, selection, and aggregation operations return new BareFrame instances.
 *
 * @example
 * ```javascript
 * const sheet = SpreadsheetApp.getActiveSheet();
 * const df = gaslamp.BareFrame.fromSheet(sheet);
 * const filtered = df.filter(row => row.get('age') >= 18);
 * const selected = filtered.select(['name', 'age']);
 * selected.toSheet(sheet);
 * ```
 *
 * @category DataFrame
 */
export class BareFrame { ... }

Interface

TypeScript
/**
 * Options for DataFrame.filter() operation.
 *
 * @category DataFrame
 */
export interface FilterOptions {
  /** Throw on error if true; return null if false. Default: false. */
  strict?: boolean;
}

Language Guidelines

Write for developers new to gaslamp:

  • Be concrete. "Removes duplicate rows" not "Operates on duplicates"
  • Use active voice. "Returns a filtered DataFrame" not "Filtering returns a DataFrame"
  • Explain benefits. Why would someone use this?
  • Avoid jargon. Explain technical terms if used

Good:

TypeScript
/** Removes duplicate rows, keeping the first of each group. Useful for cleaning imported data. */

Bad:

TypeScript
/** Deduplicates using a hash-based algorithm. */

Sample Code Requirements

All code examples in docstrings must:

  1. Use javascript language identifier (not typescript)
  2. Examples must be executable in Google Apps Script

  3. No type annotations in function signatures

  4. Use gaslamp. prefix for all API calls

  5. ✓ gaslamp.BareFrame.fromSheet()
  6. ✓ gaslamp.FlameGuards.isNumber()

  7. ✗ BareFrame.fromSheet() (wrong)

  8. Show realistic GAS usage when applicable

  9. Reference SpreadsheetApp correctly

  10. Show complete workflows (read → transform → write)

  11. Use console methods for logging (V8 runtime)

  12. ✓ console.log() — General output (DEBUG level)
  13. ✓ console.info() — Informational messages (INFO level)
  14. ✓ console.warn() — Warning messages (WARNING level)
  15. ✓ console.error() — Error messages (ERROR level)
  16. ✗ console.debug() — Not supported in GAS
  17. Never use Logger.log() — console is preferred for V8 runtime

Example:

JavaScript
// Read from active sheet
const sheet = SpreadsheetApp.getActiveSheet();
const df = gaslamp.BareFrame.fromSheet(sheet);

// Transform
const filtered = df.filter(row => row.get('age') >= 18);
const selected = filtered.select(['name', 'age']);

// Output results
if (selected.length === 0) {
  console.warn('No rows matched the filter');
} else {
  console.log(`Found ${selected.length} rows`);
}

// Write to new sheet
const output = SpreadsheetApp.getActiveSpreadsheet().insertSheet('clean');
selected.toSheet(output);

Pre-Commit Checklist

Before committing, verify:

  • Summary is one sentence, present tense?
  • All parameters documented in @param?
  • Return value documented in @returns?
  • Has a @category?
  • Example uses javascript identifier?
  • Example uses gaslamp. prefix?
  • Example uses console methods (not Logger.log)?
  • Example is executable in GAS (no TypeScript syntax)?
  • No implementation details leaked into the description?