code-documentation

What is it?

This skill manages adding documentation to code. It covers documenting constants, variables, functions, classes, and modules in a consistent, clear, and maintainable way.

Success Criteria

• Constants, variables, functions, classes, and modules are documented with clear descriptions.
• Parameters, return values, and types are explained where applicable.
• Documentation uses a consistent style (e.g., JSDoc for JavaScript, docstrings for Python).
• Examples are included when necessary.
• Documentation is updated whenever code changes.

When to use this skill

• "Document the new function I just wrote."
• "Add docstrings to all classes in this file."
• "Explain the constants and variables in this module."
• "Generate documentation for parameters and return values."
• "Check that all public functions are documented."

What this skill can do

• Constants: Add descriptions, types, and usage notes.
• Variables: Explain purpose, type, and constraints.
• Functions: Document purpose, parameters, return values, side effects, and examples.
• Classes: Describe the class, properties, methods, and usage.
• Modules: Provide high-level overview of what the module contains.
• Style enforcement: Ensure documentation uses a consistent format.

What this skill will NOT do

• Execute code.
• Automatically refactor undocumented code.
• Create diagrams or visual documentation.

How to use this skill

1. Identify Code Element: Determine if it’s a constant, variable, function, class, or module.
2. Select Style: Choose the documentation format (e.g., JSDoc, Python docstring, TypeScript type annotations).
3. Document: Add description, type info, parameters, return values, examples, and notes.
4. Validate: Ensure the documentation is clear, concise, and consistent.

Documentation rules

• Constants: Include a short description and purpose. Mention constraints or limits if applicable.

• Variables: Describe its role, type, initial value, and constraints.

• Functions: Always document:

  • Description: What it does
  • Parameters: Name, type, and purpose
  • Return Value: Type and meaning
  • Side Effects: If any
  • Example: Optional usage example

• Classes: Document:

  • Class description: What it represents
  • Properties: Name, type, description
  • Methods: Include function documentation for each method

• Modules: Give a high-level overview of contents and purpose.

• Consistency: Use the same format across the project.

• Update: When code changes, produce a doc patch or flag outdated docs in the same PR; run linter to verify updates

• Examples: Include examples whenever it helps clarify usage.

Examples

• Constant

/**
 * Maximum number of users allowed in the system.
 */
const MAX_USERS = 100;

• Variable

/**
 * Current number of active users.
 * Type: number
 */
let userCount = 0;

• Function

/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 */
function calculateSum(a, b) {
  return a + b;
}

• Class

/**
 * Represents a user in the system.
 */
class User {
  /**
   * @param {string} name - Name of the user
   * @param {number} age - Age of the user
   */
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }

  /**
   * Greets the user.
   * @returns {string} Greeting message
   */
  greet() {
    return `Hello, ${this.name}`;
  }
}

Limitations

• Cannot enforce style automatically; depends on developer to apply consistently.
• Cannot document private or internal logic unless explicitly instructed.
• Examples are illustrative; may need adaptation for production code.