Documentation

This skill enforces documentation standards across README files, inline comments, and component APIs. It ensures code is self-documenting and maintainable by requiring clear explanations of intent rather than restating the obvious.

npx skills add Rugved1652/vayu-ui/document-code

Guidelines for writing clear, maintainable documentation at every level of the codebase.

README Standards

Every package and major feature should have a README containing:

• Purpose — What this code does and why it exists
• Installation — How to add it to a project
• Usage — Minimal working example
• API — Key functions, props, or configuration options
• Contributing — How to extend or modify

Inline Comments

Comment the "why", not the "what":

// Good: Explains business logic
// Invalidate cache after mutation to ensure UI stays in sync
queryClient.invalidateQueries({ queryKey: ['users'] });

// Bad: Restates the obvious
// Call invalidateQueries
queryClient.invalidateQueries({ queryKey: ['users'] });

Component Documentation

Document component props using JSDoc or TypeScript interfaces:

interface ButtonProps {
  /** The visual style of the button */
  variant?: 'primary' | 'secondary' | 'ghost';
  /** Button size affecting padding and font */
  size?: 'sm' | 'md' | 'lg';
  /** Disables the button and shows a loading state */
  isLoading?: boolean;
}

Code Examples

Include runnable examples in documentation:

• Use the actual component, not pseudocode
• Show real-world usage patterns
• Include error handling where relevant

Anti-Patterns

• Outdated documentation — Keep docs in sync with code changes
• Obvious comments — // increment counter on counter++
• Missing README — Every package needs an entry point for developers
• Undocumented props — Every public API surface needs explanation