API Summary Document Creation

Guidelines for creating api_summary_{module}.md files that document the public API of a module for end users.

---

Purpose

API summary documents provide a user-friendly reference for all public classes, functions, and global variables in a module. These documents generate user documentation in Markdown format.

---

Which packages carry `doc/api/`

A package whose public API somebody imports — a library, a framework package — carries the doc/api/ summaries this guideline describes. An application package with no importable surface (a Flutter app, a demo harness) does not: nothing imports it, so there is no API for a summary to describe, and one written over its internals would drift with nothing to notice. Its README says so, in the same place it says why there is no example/, and points at the map a reader of an application needs instead — a demo catalogue, a screen list.

---

Coverage Requirements

1. Dart files: Create API summary for all Dart files in the module folder, scanning all subfolders 2. Public members only: Exclude all private members (starting with _) 3. Public classes only: Exclude all private classes (starting with _) 4. All public API: Include classes, functions, constants, and global variables 5. Preserve inheritance: Document class hierarchies accurately

---

File Location and Naming

Item	Convention
Location	`{project}/doc/api/`
File naming	`api_summary_{module}.md` (lowercase, underscores)
Index file	`api_summary_index.md`

---

Document Structure

Each API summary document follows this structure:

1. Title

# {Project} API Reference: {Module Name} Module

2. Table of Contents

## Table of Contents

- [Overview](#overview)
- [Class Hierarchy](#class-hierarchy)
- [Classes](#classes)
  - [ClassName1](#classname1)
  - [ClassName2](#classname2)
- [Global Functions and Constants](#global-functions-and-constants)

3. Overview

One-paragraph summary of what the module provides.

## Overview

The {Module} module provides {brief description of functionality}.

4. Class Hierarchy

ASCII art showing inheritance relationships:

## Class Hierarchy

\`\`\`
Object
├── ParentClass
│   └── ChildClass
├── AnotherClass
└── (interfaces)
    └── SomeInterface
\`\`\`

5. Classes Section

Each class gets its own subsection:

## Classes

### ClassName

Brief description of the class purpose.

**Extends:** `ParentClass`
**Implements:** `Interface1`, `Interface2`
**Type Parameters:** `<T>`

#### Constructors

\`\`\`dart
ClassName(
  Type param1, {
  Type? optionalParam,
})
\`\`\`

#### Factory Constructors

\`\`\`dart
factory ClassName.named(params)
\`\`\`

#### Static Properties

| Property | Type | Description |
|----------|------|-------------|
| `propertyName` | `Type` | Description |

#### Static Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `methodName(params)` | `ReturnType` | Description |

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| `propertyName` | `Type` | Description |

#### Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `methodName(params)` | `ReturnType` | Description |

#### Operators

| Operator | Return Type | Description |
|----------|-------------|-------------|
| `operator +(other)` | `Type` | Description |

6. Global Functions and Constants

## Global Functions and Constants

### Constants

| Constant | Type | Description |
|----------|------|-------------|
| `constantName` | `Type` | Description |

### Functions

| Function | Signature | Description |
|----------|-----------|-------------|
| `functionName` | `ReturnType functionName(params)` | Description |

---

Content Rules

Coverage

1. Public members only - Exclude all private members (starting with _) 2. Public classes only - Exclude all private classes (starting with _) 3. All public API - Include classes, functions, constants, and global variables

Class Documentation

Section	When to Include
Extends	Always if class extends something other than Object
Implements	If class implements interfaces
Type Parameters	If class is generic
Constructors	All public constructors
Factory Constructors	All factory constructors, listed separately
Static Properties	Class-level static fields and getters
Static Methods	Class-level static methods
Properties	Instance fields and getters/setters
Methods	Instance methods
Inherited Properties	Only for exception classes or when inheritance is important
Inherited Methods	Only for exception classes or when inheritance is important
Operators	If class overloads operators

Table Formatting

Use consistent table format with pipes and headers:

| Column1 | Column2 | Column3 |
|---------|---------|---------|
| value1  | value2  | value3  |

Code Blocks

Use dart language identifier for code blocks
Show full constructor signatures with named parameters
Include type annotations

---

API Summary Index

The api_summary_index.md file provides navigation across all module summaries.

Structure

1. Title and Introduction 2. Table of Contents - All modules and sections 3. Quick Navigation Table - Links to both reference and guide for each module 4. Per-Module Summary Tables - Classes, Functions, and Global Variables with links 5. Alphabetical Indexes - Classes, Functions, Global Variables sorted A-Z

Quick Navigation Table Format

## Quick Navigation

| Module Reference | Module Guide | Description |
|------------------|--------------|-------------|
| [Module Name](api_summary_module.md) | [Guide](../module/module.md) | Brief description |

Per-Module Summary Table Format

## {Module Name} Module

### Classes

| Class | Description | Link |
|-------|-------------|------|
| `ClassName` | Brief description | [→](api_summary_module.md#classname) |

### Functions

| Function | Signature | Description | Link |
|----------|-----------|-------------|------|
| `functionName` | `ReturnType functionName(params)` | Description | [→](api_summary_module.md#functions) |

### Global Variables

| Variable | Type | Description | Link |
|----------|------|-------------|------|
| `varName` | `Type` | Description | [→](api_summary_module.md#constants) |

Alphabetical Index Format

## Alphabetical Class Index

| Class | Module | Link |
|-------|--------|------|
| `ClassName` | Module Name | [→](api_summary_module.md#classname) |

---

Example: Bean Locator Module

# TomBase API Reference: Bean Locator Module

## Table of Contents

- [Overview](#overview)
- [Class Hierarchy](#class-hierarchy)
- [Classes](#classes)
  - [TomBeanLocatorException](#tombeanlocatorexception)
  - [TomComponent](#tomcomponent)
  - [TomBean\<T\>](#tombeant)
- [Global Functions and Constants](#global-functions-and-constants)

---

## Overview

The Bean Locator module provides a lightweight dependency injection container 
that uses Dart reflection to automatically discover, instantiate, and wire 
service beans.

---

## Class Hierarchy

\`\`\`
Object
├── TomException
│   └── TomBeanLocatorException
├── TomComponent
└── TomBean<T>
\`\`\`

---

## Classes

### TomBeanLocatorException

Exception thrown when bean locator operations fail.

**Extends:** `TomException`

#### Constructors

\`\`\`dart
TomBeanLocatorException(
  String key,
  String defaultUserMessage, {
  Map<String, Object?>? parameters,
  Object? stack,
  Object? rootException,
  bool autoLog = false,
})
\`\`\`

#### Inherited Properties

| Property | Type | Description |
|----------|------|-------------|
| `uuid` | `String` | Unique identifier for this exception |
| `key` | `String` | Error key/code |
| `defaultUserMessage` | `String` | User-friendly error message |

---

### TomComponent

Annotation to mark a class as a Tom component/service bean.

---

## Global Functions and Constants

### Constants

| Constant | Type | Description |
|----------|------|-------------|
| `tomComponent` | `TomComponent` | Default annotation for beans |

### Functions

| Function | Signature | Description |
|----------|-----------|-------------|
| `initializeBeanContext` | `void initializeBeanContext()` | Initializes bean context |

---

Relationship to Other Documents

Document	Purpose
api_summary_creation.md	Rules for creating API summary documentation (this file)
api_reference_creation.md	Process for combining summaries into PDF
documentation_guidelines.md	General documentation structure and file placement