documentation-linking

# Documentation Linking

Creating and maintaining bidirectional links between code and documentation for AI-assisted development.

## Bidirectional Linking

### Code → Documentation

Link from code to relevant documentation:

```typescript
/**
 * Implements the authentication flow described in:
 * @doc docs/architecture/authentication.md#oauth-flow
 * @api-spec api/openapi.yaml#/components/securitySchemes/oauth2
 * @decision-record docs/decisions/003-oauth-provider.md
 *
 * Related endpoints:
 * - POST /auth/login (login initiation)
 * - GET /auth/callback (OAuth callback)
 * - POST /auth/refresh (token refresh)
 */
export class AuthenticationService {
  // Implementation
}
```

### Documentation → Code

Link from documentation to implementing code:

```markdown
# Authentication Flow

Our OAuth 2.0 authentication flow is implemented in:

- Main logic: `src/services/AuthenticationService.ts`
- Routes: `src/routes/auth.ts:15-45`
- Middleware: `src/middleware/auth.ts:78`
- Tests: `tests/integration/auth.test.ts`

See also:
- Database schema: `migrations/003_create_users.sql`
- Configuration: `config/auth.yaml`
```

## Link Formats

### Absolute Links

```python
# @doc /docs/database/migrations.md#schema-versioning
# Full path from repository root
```

### Relative Links

```javascript
// @doc ../../../docs/api/rest-endpoints.md#user-endpoints
// Relative to current file
```

### Line-Specific Links

```go
// @impl service/user_service.go:145-178
// Links to specific line range
```

### Anchor Links

```rust
/// @doc architecture.md#data-flow-diagram
/// Links to specific section via anchor
```

## Documentation Types

### Architecture Documentation

```typescript
/**
 * @arch-doc docs/architecture/system-overview.md
 * @component-diagram docs/diagrams/user-service.svg
 * @sequence-diagram docs/diagrams/login-flow.puml
 *
 * This service is part of the user management subsystem.
 * See architecture docs for component interactions and data flow.
 */
class UserService {