open-circle/repo-source-code-document

Source Code Documentation

A concise guide for documenting Formisch source code with JSDoc and inline comments.

Core Principles

1. Clarity over verbosity - Be precise and concise
2. Consistency is critical - Same APIs use identical documentation across all frameworks
3. User-focused - Documentation enhances TypeScript IntelliSense
4. Group related code - Comment logical blocks, not every line

JSDoc Patterns

Interfaces and Types

First line format:

• [Name] [category] interface. → "Form store interface."
• [Name] [category] type. → "Validation mode type."

Special cases:

• Config: "Use field config interface."
• Store: "Form store interface."
• Props: "Field element props interface."

/**
 * Form store interface.
 */
export interface FormStore<TSchema extends Schema> {
  /**
   * Whether the form is currently submitting.
   */
  readonly isSubmitting: ReadonlySignal<boolean>;
  /**
   * The current error messages of the form.
   */
  readonly errors: ReadonlySignal<[string, ...string[]] | null>;
}

Property patterns:

• Boolean state: Whether the [subject] [condition].
• Data properties: The current [description].
• Path properties: The path to the [description] within the form.
• Element props: The [description] of the field element.

Functions

Overload signatures only (no JSDoc on implementation):

/**
 * Creates a reactive field store of a specific field within a form store.
 *
 * @param form The form store instance.
 * @param config The field configuration.
 *
 * @returns The field store with reactive properties and element props.
 */
export function useField<TSchema, TFieldPath>(
  form: FormStore<TSchema>,
  config: UseFieldConfig<TSchema, TFieldPath>
): FieldStore<TSchema, TFieldPath>;

// @__NO_SIDE_EFFECTS__
export function useField(form: FormStore, config: UseFieldConfig): FieldStore {
  // Implementation (no JSDoc)
}

Rules:

• First line: Action-focused description (present tense, third person)
• Start with verbs: "Creates", "Initializes", "Resets", "Validates"
• @param: The [description]. (start with "The", end with period)
• @returns: The [description]. (describe what is returned)
• Add // @__NO_SIDE_EFFECTS__ for pure functions only

Constants

/**
 * Internal symbol constant.
 */
export const INTERNAL = '~internal' as const;

Barrel Files

No JSDoc and inline comments needed - keep clean.

Inline Comments

Style Rules

• No articles ("the", "a", "an") except in Hints
• No periods at end except in Hints and TODOs
• Use present tense verbs
• Blank line before comment, none after

Section Headers

Mark major logic blocks:

// Get input value from field store
const input = getFieldInput(internalFieldStore);

// If validation is required, perform validation
if (shouldValidate) {
  // implementation
}

Conditionals

// If field is touched, validate
if (isTouched) {
  validate();
}

// Otherwise, if validation mode is initial, validate
else if (validate === 'initial') {
  performValidation();
}

// Otherwise, skip validation
else {
  return;
}

Operations

Group related operations under one comment:

// Set validation configuration
store.validators = 0;
store.validate = config.validate ?? 'submit';
store.revalidate = config.revalidate ?? 'input';

Hints

Explain WHY, not WHAT. Can use articles and periods:

// Hint: The object is deliberately not constructed with spread operator
// for performance reasons
const obj = { prop: value };

In JSDoc:

/**
 * The initial input of the field.
 *
 * Hint: The initial input is used for resetting and may only be changed
 * during this process. It does not move when a field is moved.
 */
initialInput: Signal<unknown>;

Cross-Framework Consistency

Same properties/functions across frameworks must use identical documentation text.

Check documentation in other frameworks before adding or modifying.

What to Document

✅ Document

• Public interfaces and types
• Exported function overloads
• Exported constants
• Interface properties
• Section headers for major logic blocks
• Each branch in long if-else chains
• Non-obvious logic (with Hints)

❌ Don't Document

• Function implementations
• Barrel/index files
• Standard loop variables (index, key, item)
• Every single line
• Obvious operations
• @ts-expect-error when context is clear

Quick Reference

JSDoc First Lines

• Interface: [Name] [category] interface.
• Type: [Name] [category] type.
• Function: Descriptive action sentence
• Constant: Brief description

JSDoc Tags

@param name The [description].
@returns The [description].
@internal (for internal APIs only)

Inline Patterns

// Get [what]
// Set [what] to [value]
// If [condition], [action]
// Otherwise, [action]
// Hint: [explanation with articles and period]
// TODO: [task]