Documentation Tools - Complete Guide

# Documentation Tools Implementation

# 1. JSDoc Documentation
## JSDoc Configuration
// jsdoc.conf.json
{
  "source": {
    "include": ["./src/"],
    "includePattern": "\\.(js|jsx|ts|tsx)$",
    "exclude": ["node_modules/", "dist/", "coverage/"]
  },
  "opts": {
    "destination": "./docs/",
    "recurse": true,
    "template": "node_modules/docdash"
  },
  "plugins": [
    "plugins/markdown",
    "plugins/summarize"
  ],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "default": {
      "outputSourceFiles": true
    }
  }
}

## JSDoc Examples
/**
 * 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
 * @throws {Error} When either parameter is not a number
 * @example
 * // Returns 5
 * add(2, 3);
 * 
 * // Returns 0
 * add(-1, 1);
 */
function add(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new Error('Both parameters must be numbers');
  }
  return a + b;
}

/**
 * User management class
 * @class
 * @example
 * const userManager = new UserManager();
 * userManager.createUser('john@example.com', 'John Doe');
 */
class UserManager {
  /**
   * Creates a new user
   * @param {string} email - User's email address
   * @param {string} name - User's full name
   * @param {Object} options - Additional options
   * @param {boolean} options.isActive - Whether user is active
   * @param {string[]} options.roles - User roles
   * @returns {Promise} Created user object
   * @throws {ValidationError} When email is invalid
   * @throws {DuplicateError} When user already exists
   */
  async createUser(email, name, options = {}) {
    // Implementation
  }

  /**
   * Finds a user by email
   * @param {string} email - User's email address
   * @returns {Promise} User object or null if not found
   */
  async findByEmail(email) {
    // Implementation
  }
}

# 2. TypeScript Documentation
## TSDoc Examples
/**
 * Represents a user in the system
 * @public
 */
interface User {
  /** Unique identifier for the user */
  id: string;
  
  /** User's email address */
  email: string;
  
  /** User's display name */
  name: string;
  
  /** Whether the user account is active */
  isActive: boolean;
  
  /** User's roles and permissions */
  roles: string[];
}

/**
 * Configuration options for the API client
 * @public
 */
interface ApiClientOptions {
  /** Base URL for API requests */
  baseUrl: string;
  
  /** API key for authentication */
  apiKey: string;
  
  /** Request timeout in milliseconds */
  timeout?: number;
  
  /** Whether to enable request/response logging */
  enableLogging?: boolean;
}

/**
 * API client for making HTTP requests
 * @public
 * @example
 * ```typescript
 * const client = new ApiClient({
 *   baseUrl: 'https://api.example.com',
 *   apiKey: 'your-api-key'
 * });
 * 
 * const user = await client.get('/users/123');
 * ```
 */
class ApiClient {
  private options: ApiClientOptions;

  /**
   * Creates a new API client instance
   * @param options - Configuration options
   */
  constructor(options: ApiClientOptions) {
    this.options = options;
  }

  /**
   * Makes a GET request
   * @param url - Request URL
   * @param params - Query parameters
   * @returns Promise resolving to response data
   * @throws {ApiError} When request fails
   */
  async get(url: string, params?: Record): Promise {
    // Implementation
  }
}

# 3. API Documentation with Swagger
## Swagger/OpenAPI Configuration
// swagger.config.js
const swaggerJSDoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User Management API',
      version: '1.0.0',
      description: 'API for managing users and authentication',
      contact: {
        name: 'API Support',
        email: 'support@example.com'
      }
    },
    servers: [
      {
        url: 'https://api.example.com',
        description: 'Production server'
      },
      {
        url: 'https://staging-api.example.com',
        description: 'Staging server'
      }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT'
        }
      },
      schemas: {
        User: {
          type: 'object',
          required: ['id', 'email', 'name'],
          properties: {
            id: {
              type: 'string',
              description: 'Unique user identifier'
            },
            email: {
              type: 'string',
              format: 'email',
              description: 'User email address'
            },
            name: {
              type: 'string',
              description: 'User display name'
            },
            isActive: {
              type: 'boolean',
              description: 'Whether user account is active'
            }
          }
        },
        Error: {
          type: 'object',
          properties: {
            message: {
              type: 'string',
              description: 'Error message'
            },
            code: {
              type: 'string',
              description: 'Error code'
            }
          }
        }
      }
    }
  },
  apis: ['./src/routes/*.js', './src/models/*.js']
};

const specs = swaggerJSDoc(options);
module.exports = specs;

## API Route Documentation
/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     tags: [Users]
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Number of users per page
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 users:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 *                 pagination:
 *                   type: object
 *                   properties:
 *                     page:
 *                       type: integer
 *                     limit:
 *                       type: integer
 *                     total:
 *                       type: integer
 *       400:
 *         description: Bad request
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Error'
 */
app.get('/users', async (req, res) => {
  // Implementation
});

/**
 * @swagger
 * /users:
 *   post:
 *     summary: Create a new user
 *     tags: [Users]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - name
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *               name:
 *                 type: string
 *               isActive:
 *                 type: boolean
 *                 default: true
 *     responses:
 *       201:
 *         description: User created successfully
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       400:
 *         description: Validation error
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Error'
 */
app.post('/users', async (req, res) => {
  // Implementation
});

# 4. Markdown Documentation
## README.md Template
# Project Name

Brief description of what the project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
npm install
```

## Usage

```javascript
const { ProjectName } = require('project-name');

const instance = new ProjectName();
instance.doSomething();
```

## API Reference

### Class: ProjectName

#### constructor(options)

Creates a new instance of ProjectName.

**Parameters:**
- `options` (Object): Configuration options
  - `option1` (string): Description of option1
  - `option2` (number): Description of option2

**Example:**
```javascript
const instance = new ProjectName({
  option1: 'value',
  option2: 42
});
```

#### method1(param1, param2)

Description of what this method does.

**Parameters:**
- `param1` (string): Description of param1
- `param2` (Object): Description of param2

**Returns:**
- (Promise): Description of return value

**Example:**
```javascript
const result = await instance.method1('value', { key: 'value' });
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT

# 5. GitBook Documentation
## GitBook Configuration
// book.json
{
  "title": "Project Documentation",
  "description": "Comprehensive documentation for the project",
  "author": "Your Name",
  "language": "en",
  "gitbook": "3.2.3",
  "structure": {
    "readme": "README.md",
    "summary": "SUMMARY.md"
  },
  "plugins": [
    "highlight",
    "search",
    "sharing",
    "fontsettings",
    "theme-default"
  ],
  "pluginsConfig": {
    "theme-default": {
      "showLevel": true
    }
  }
}

## SUMMARY.md
# Table of contents

* [Introduction](README.md)
* [Getting Started](getting-started.md)
* [API Reference](api-reference.md)
  * [Authentication](api-reference/authentication.md)
  * [Users](api-reference/users.md)
  * [Posts](api-reference/posts.md)
* [Configuration](configuration.md)
* [Deployment](deployment.md)
* [Contributing](contributing.md)

# 6. Docusaurus Documentation
## Docusaurus Configuration
// docusaurus.config.js
module.exports = {
  title: 'Project Documentation',
  tagline: 'Comprehensive project documentation',
  url: 'https://docs.example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'your-org',
  projectName: 'project-docs',
  
  themeConfig: {
    navbar: {
      title: 'Project Docs',
      logo: {
        alt: 'Project Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          to: 'docs/',
          activeBasePath: 'docs',
          label: 'Docs',
          position: 'left',
        },
        {
          to: 'api/',
          activeBasePath: 'api',
          label: 'API',
          position: 'left',
        },
        {
          href: 'https://github.com/your-org/project',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Getting Started',
              to: 'docs/',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'Stack Overflow',
              href: 'https://stackoverflow.com/questions/tagged/project',
            },
          ],
        },
        {
          title: 'More',
          items: [
            {
              label: 'GitHub',
              href: 'https://github.com/your-org/project',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} Your Project.`,
    },
  },
  
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/your-org/project/edit/main/docs/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
};

# 7. Storybook Documentation
## Storybook Configuration
// .storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-docs',
    '@storybook/addon-controls',
    '@storybook/addon-viewport',
  ],
  framework: '@storybook/react',
  core: {
    builder: '@storybook/builder-webpack5',
  },
  docs: {
    autodocs: 'tag',
  },
};

## Component Story Example
// src/components/Button.stories.js
import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: 'A simple button component with various styles and sizes.',
      },
    },
  },
  argTypes: {
    backgroundColor: { control: 'color' },
    size: {
      control: { type: 'select' },
      options: ['small', 'medium', 'large'],
    },
  },
};

export const Primary = {
  args: {
    primary: true,
    label: 'Button',
  },
};

export const Secondary = {
  args: {
    label: 'Button',
  },
};

export const Large = {
  args: {
    size: 'large',
    label: 'Button',
  },
};

export const Small = {
  args: {
    size: 'small',
    label: 'Button',
  },
};

# 8. Documentation Automation
## Documentation Generation Script
// scripts/generateDocs.js
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

class DocumentationGenerator {
  constructor() {
    this.projectRoot = process.cwd();
    this.docsDir = path.join(this.projectRoot, 'docs');
  }

  async generateAll() {
    console.log('Generating documentation...');
    
    await this.generateJSDoc();
    await this.generateAPI();
    await this.generateREADME();
    await this.generateChangelog();
    
    console.log('Documentation generation completed!');
  }

  async generateJSDoc() {
    console.log('Generating JSDoc...');
    
    try {
      execSync('npx jsdoc -c jsdoc.conf.json', { stdio: 'inherit' });
      console.log('JSDoc generated successfully');
    } catch (error) {
      console.error('JSDoc generation failed:', error.message);
    }
  }

  async generateAPI() {
    console.log('Generating API documentation...');
    
    try {
      execSync('npx swagger-jsdoc -d swagger.config.js -o docs/api.json', { stdio: 'inherit' });
      console.log('API documentation generated successfully');
    } catch (error) {
      console.error('API documentation generation failed:', error.message);
    }
  }

  async generateREADME() {
    console.log('Generating README...');
    
    const readmeContent = this.generateReadmeContent();
    const readmePath = path.join(this.projectRoot, 'README.md');
    
    fs.writeFileSync(readmePath, readmeContent);
    console.log('README generated successfully');
  }

  async generateChangelog() {
    console.log('Generating changelog...');
    
    try {
      execSync('npx conventional-changelog -p angular -i CHANGELOG.md -s', { stdio: 'inherit' });
      console.log('Changelog generated successfully');
    } catch (error) {
      console.error('Changelog generation failed:', error.message);
    }
  }

  generateReadmeContent() {
    const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
    
    return `# ${packageJson.name}

${packageJson.description}

## Installation

\`\`\`bash
npm install ${packageJson.name}
\`\`\`

## Usage

\`\`\`javascript
const { ${packageJson.name} } = require('${packageJson.name}');

// Usage example
\`\`\`

## API Reference

See [API Documentation](./docs/api.md) for detailed API reference.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

${packageJson.license}
`;
  }
}

const generator = new DocumentationGenerator();
generator.generateAll();

# 9. Documentation Testing
## Documentation Test Suite
// tests/documentation.test.js
const fs = require('fs');
const path = require('path');

describe('Documentation', () => {
  test('README exists and is not empty', () => {
    const readmePath = path.join(process.cwd(), 'README.md');
    expect(fs.existsSync(readmePath)).toBe(true);
    
    const content = fs.readFileSync(readmePath, 'utf8');
    expect(content.length).toBeGreaterThan(0);
  });

  test('API documentation is up to date', () => {
    const apiPath = path.join(process.cwd(), 'docs', 'api.json');
    expect(fs.existsSync(apiPath)).toBe(true);
    
    const apiDoc = JSON.parse(fs.readFileSync(apiPath, 'utf8'));
    expect(apiDoc.info).toBeDefined();
    expect(apiDoc.paths).toBeDefined();
  });

  test('All public methods have JSDoc comments', () => {
    const srcDir = path.join(process.cwd(), 'src');
    const files = this.getJSFiles(srcDir);
    
    files.forEach(file => {
      const content = fs.readFileSync(file, 'utf8');
      const publicMethods = this.extractPublicMethods(content);
      
      publicMethods.forEach(method => {
        expect(this.hasJSDocComment(content, method)).toBe(true);
      });
    });
  });

  getJSFiles(dir) {
    const files = [];
    const items = fs.readdirSync(dir);
    
    items.forEach(item => {
      const fullPath = path.join(dir, item);
      const stat = fs.statSync(fullPath);
      
      if (stat.isDirectory()) {
        files.push(...this.getJSFiles(fullPath));
      } else if (item.endsWith('.js') || item.endsWith('.ts')) {
        files.push(fullPath);
      }
    });
    
    return files;
  }

  extractPublicMethods(content) {
    const methods = [];
    const regex = /(?:export\s+)?(?:public\s+)?(?:async\s+)?(?:function\s+)?(\w+)\s*\(/g;
    let match;
    
    while ((match = regex.exec(content)) !== null) {
      methods.push(match[1]);
    }
    
    return methods;
  }

  hasJSDocComment(content, method) {
    const methodIndex = content.indexOf(method);
    const beforeMethod = content.substring(0, methodIndex);
    return beforeMethod.includes('/**');
  }
});

# 10. Documentation Maintenance
## Documentation Maintenance Script
// scripts/maintainDocs.js
const fs = require('fs');
const path = require('path');

class DocumentationMaintainer {
  constructor() {
    this.projectRoot = process.cwd();
    this.docsDir = path.join(this.projectRoot, 'docs');
  }

  async maintain() {
    console.log('Maintaining documentation...');
    
    await this.checkBrokenLinks();
    await this.updateLastModified();
    await this.validateExamples();
    await this.checkConsistency();
    
    console.log('Documentation maintenance completed!');
  }

  async checkBrokenLinks() {
    console.log('Checking for broken links...');
    
    const files = this.getMarkdownFiles(this.docsDir);
    const brokenLinks = [];
    
    files.forEach(file => {
      const content = fs.readFileSync(file, 'utf8');
      const links = this.extractLinks(content);
      
      links.forEach(link => {
        if (!this.isValidLink(link)) {
          brokenLinks.push({ file, link });
        }
      });
    });
    
    if (brokenLinks.length > 0) {
      console.warn('Broken links found:');
      brokenLinks.forEach(({ file, link }) => {
        console.warn(`  ${file}: ${link}`);
      });
    } else {
      console.log('No broken links found');
    }
  }

  async updateLastModified() {
    console.log('Updating last modified dates...');
    
    const files = this.getMarkdownFiles(this.docsDir);
    
    files.forEach(file => {
      const content = fs.readFileSync(file, 'utf8');
      const updatedContent = this.updateLastModifiedDate(content);
      fs.writeFileSync(file, updatedContent);
    });
    
    console.log('Last modified dates updated');
  }

  async validateExamples() {
    console.log('Validating code examples...');
    
    const files = this.getMarkdownFiles(this.docsDir);
    const invalidExamples = [];
    
    files.forEach(file => {
      const content = fs.readFileSync(file, 'utf8');
      const examples = this.extractCodeExamples(content);
      
      examples.forEach(example => {
        if (!this.isValidCodeExample(example)) {
          invalidExamples.push({ file, example });
        }
      });
    });
    
    if (invalidExamples.length > 0) {
      console.warn('Invalid code examples found:');
      invalidExamples.forEach(({ file, example }) => {
        console.warn(`  ${file}: ${example.substring(0, 50)}...`);
      });
    } else {
      console.log('All code examples are valid');
    }
  }

  async checkConsistency() {
    console.log('Checking documentation consistency...');
    
    const files = this.getMarkdownFiles(this.docsDir);
    const inconsistencies = [];
    
    files.forEach(file => {
      const content = fs.readFileSync(file, 'utf8');
      const issues = this.findInconsistencies(content);
      
      if (issues.length > 0) {
        inconsistencies.push({ file, issues });
      }
    });
    
    if (inconsistencies.length > 0) {
      console.warn('Inconsistencies found:');
      inconsistencies.forEach(({ file, issues }) => {
        console.warn(`  ${file}:`);
        issues.forEach(issue => console.warn(`    - ${issue}`));
      });
    } else {
      console.log('No inconsistencies found');
    }
  }

  getMarkdownFiles(dir) {
    const files = [];
    const items = fs.readdirSync(dir);
    
    items.forEach(item => {
      const fullPath = path.join(dir, item);
      const stat = fs.statSync(fullPath);
      
      if (stat.isDirectory()) {
        files.push(...this.getMarkdownFiles(fullPath));
      } else if (item.endsWith('.md')) {
        files.push(fullPath);
      }
    });
    
    return files;
  }

  extractLinks(content) {
    const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const links = [];
    let match;
    
    while ((match = linkRegex.exec(content)) !== null) {
      links.push(match[2]);
    }
    
    return links;
  }

  isValidLink(link) {
    if (link.startsWith('http')) {
      return true; // External links
    }
    
    const filePath = path.join(this.docsDir, link);
    return fs.existsSync(filePath);
  }

  updateLastModifiedDate(content) {
    const lastModifiedRegex = /Last modified: \d{4}-\d{2}-\d{2}/;
    const currentDate = new Date().toISOString().split('T')[0];
    
    if (lastModifiedRegex.test(content)) {
      return content.replace(lastModifiedRegex, `Last modified: ${currentDate}`);
    } else {
      return content + `\n\nLast modified: ${currentDate}`;
    }
  }

  extractCodeExamples(content) {
    const codeBlockRegex = /```[\s\S]*?```/g;
    const examples = [];
    let match;
    
    while ((match = codeBlockRegex.exec(content)) !== null) {
      examples.push(match[0]);
    }
    
    return examples;
  }

  isValidCodeExample(example) {
    // Basic validation for code examples
    return example.length > 10 && example.includes('```');
  }

  findInconsistencies(content) {
    const issues = [];
    
    // Check for inconsistent terminology
    if (content.includes('API') && content.includes('api')) {
      issues.push('Inconsistent API capitalization');
    }
    
    // Check for inconsistent formatting
    if (content.includes('**bold**') && content.includes('__bold__')) {
      issues.push('Inconsistent bold formatting');
    }
    
    return issues;
  }
}

const maintainer = new DocumentationMaintainer();
maintainer.maintain();