Content Loading

/**
 * Defines the @load tag for JSDoc
 * @param {Object} dictionary - JSDoc tag dictionary for registering new tags
 */
function defineTags(dictionary: Object): void;

interface TagDefinition {
  /**
   * Called when @load tag is encountered during parsing
   * @param {Object} doclet - JSDoc doclet being processed
   * @param {Object} tag - The @load tag information
   */
  onTagged(doclet: Object, tag: Object): void;
}

/**
 * Loads and processes content from external files
 * @param {Object} loadTag - JSDoc load tag containing file path
 * @param {string} docletFilePath - Base path for resolving relative file paths
 * @returns {string} Processed content ready for inclusion in documentation
 */
function load(loadTag: Object, docletFilePath: string): string;

interface LoadTag {
  /** File path to load (relative to docletFilePath) */
  value: string;
}

/**
 * Processes content to fill component preview placeholders
 * @param {string} body - Raw content body
 * @param {Function} mdParser - Markdown parser function
 * @returns {string} Processed content with component previews
 */
function fillComponentPreview(body: string, mdParser: Function): string;

/**
 * User Management Service
 * 
 * @load ./user-service-examples.md
 * 
 * This service provides comprehensive user management functionality.
 */
class UserService {
  /**
   * Creates a new user
   * @param {Object} userData - User data
   * @returns {Promise<User>} Created user
   */
  async createUser(userData) {
    // Implementation
  }
}

## Usage Examples

### Creating a User

```javascript
const userService = new UserService();
const newUser = await userService.createUser({
  name: 'John Doe',
  email: 'john@example.com'
});

const users = await userService.findUsers({ active: true });

### Loading Component Examples

Load component examples and interactive previews:

```javascript
/**
 * Button Component
 * 
 * @component
 * @load ./button-examples.md
 */
const Button = ({ variant, children, onClick }) => {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {children}
    </button>
  );
};

## Button Examples

### Basic Usage

```javascript
<Button variant="primary">Click Me</Button>

<Button variant="secondary" onClick={() => alert('Clicked!')}>
  Alert Button
</Button>

### Loading API Documentation

Load detailed API documentation from separate files:

```javascript
/**
 * Database Connection Manager
 * 
 * @load ./database-api.md
 * 
 * Manages database connections with pooling and failover support.
 */
class DatabaseManager {
  /**
   * Executes a query
   * @load ./query-examples.md
   */
  async query(sql, params) {
    // Implementation
  }
}

/**
 * HTTP Client Utility
 * 
 * @load ./http-client-usage.md
 */
class HttpClient {
  /**
   * Performs GET request
   * @param {string} url - Request URL
   * @returns {Promise<Response>} HTTP response
   * 
   * @load ./get-request-examples.md
   */
  async get(url) {
    // Implementation  
  }

  /**
   * Performs POST request
   * @param {string} url - Request URL
   * @param {Object} data - Request data
   * @returns {Promise<Response>} HTTP response
   * 
   * @load ./post-request-examples.md
   */
  async post(url, data) {
    // Implementation
  }
}

/**
 * Authentication Service
 * 
 * Provides secure authentication and authorization functionality.
 * 
 * @load ./auth-examples.md
 * 
 * @see {@link TokenManager} for token management
 * @see {@link UserService} for user operations
 */
class AuthService {
  // Implementation
}

project/
├── src/
│   ├── services/
│   │   ├── user.service.js     // Contains @load ./examples/user-examples.md
│   │   └── examples/
│   │       └── user-examples.md
│   └── components/
│       ├── button.component.js // Contains @load ../docs/button-docs.md
│       └── docs/
│           └── button-docs.md

{
  "plugins": [
    "node_modules/better-docs/load"
  ]
}

src/
├── components/
│   ├── button/
│   │   ├── Button.js
│   │   ├── Button.examples.md
│   │   └── Button.stories.md
│   └── modal/
│       ├── Modal.js
│       ├── Modal.examples.md
│       └── Modal.api.md
├── services/
│   ├── api/
│   │   ├── ApiService.js
│   │   └── api-examples.md
│   └── auth/
│       ├── AuthService.js
│       └── auth-examples.md
└── docs/
    ├── common-examples.md
    └── shared-patterns.md

/**
 * Base API Service
 * @load ../docs/common-api-patterns.md
 */
class BaseApiService {
  // Implementation
}

/**
 * User API Service  
 * @load ../docs/common-api-patterns.md
 * @load ./user-api-examples.md
 */
class UserApiService extends BaseApiService {
  // Implementation
}