documentation-linking

What this skill does

# 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 {
  // Implementation
}
```

### API Documentation

```python
# @api-doc docs/api/rest-api.md#POST-/users
# @openapi-spec api/openapi.yaml#/paths/~1users/post
# @example docs/examples/create-user.md
#
# REST endpoint for creating users. API contract is defined in OpenAPI spec.
# Changes to request/response format must update both code and spec.

@app.post("/users")
async def create_user(user: UserCreate) -> User:
    """
    @request-example:
      POST /users
      {
        "email": "[email protected]",
        "name": "John Doe"
      }

    @response-example:
      201 Created
      {
        "id": 123,
        "email": "[email protected]",
        "name": "John Doe",
        "created_at": "2025-12-04T10:00:00Z"
      }
    """
    # Implementation
```

### Decision Records

```java
/**
 * @decision-record docs/decisions/005-caching-strategy.md
 *
 * DECISION: Using Redis for caching instead of in-memory cache
 * RATIONALE: Need distributed cache for horizontal scaling
 * DATE: 2025-11-15
 *
 * This implements the caching strategy defined in ADR-005.
 * Cache invalidation rules:
 * 1. Time-based: 5 minute TTL
 * 2. Event-based: Invalidate on user.updated event
 * 3. Manual: Admin can clear cache via /admin/cache/clear
 */
public class CacheService {
    // Implementation following decision record
}
```

### Test Documentation

```go
// @test-doc docs/testing/integration-tests.md#database-tests
// @test-data fixtures/users.json
// @test-cases tests/integration/user_test.go
//
// Integration tests use Docker containers for PostgreSQL.
// Test data is loaded from fixtures before each test.
// See test documentation for setup instructions.

func TestUserRepository(t *testing.T) {
    // Test implementation
}
```

### Runbook Links

```python
# @runbook docs/runbooks/incident-response.md#database-failover
# @monitoring dashboard/database-health
# @alerts alerts/database-connection-pool
#
# Database connection pool monitoring and failover logic.
# If pool exhaustion alert fires, follow runbook for mitigation steps.

class DatabaseConnectionPool:
    """
    @metric connection_pool_active (gauge)
    @metric connection_pool_idle (gauge)
    @metric connection_pool_wait_time (histogram)

    Alert thresholds:
    - connection_pool_active > 90% of max_connections for 5min
    - connection_pool_wait_time p95 > 1000ms
    """
    # Implementation
```

## Cross-Referencing Patterns

### Issue/Ticket References

```typescript
/**
 * @issue https://github.com/org/repo/issues/1234
 * @pr https://github.com/org/repo/pull/1245
 * @jira PROJ-567
 *
 * Implements user story PROJ-567: Real-time notification system
 * See issue #1234 for requirements discussion
 * See PR #1245 for implementation review and feedback
 */
class NotificationService {
  // Implementation
}
```

### Wiki/Confluence Links

```python
# @wiki https://wiki.company.com/display/ENG/Data+Pipeline
# @confluence https://company.atlassian.net/wiki/spaces/ARCH/pages/123456
#
# Data pipeline architecture documented in company wiki.
# This implements the extraction phase of the ETL pipeline.

class DataExtractor:
    # Implementation
```

### External Resources

```rust
/// @rfc https://tools.ietf.org/html/rfc7519
/// @spec https://openid.net/specs/openid-connect-core-1_0.html
/// @tutorial https://auth0.com/docs/secure/tokens/json-web-tokens
///
/// JWT implementation following RFC 7519 specification.
/// Supports OpenID Connect extensions per OIDC Core spec.

pub struct JwtToken {
    // Implementation
}
```

## Synchronization Strategies

### Automated Link Validation

Script to validate documentation links:

```bash
#!/bin/bash
# validate-doc-links.sh

# Extract all @doc references from code
grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "ERROR: Broken doc link: $doc_path"
    echo "  Referenced in: $line"
  fi
done
```

### Documentation Coverage

Track which code has documentation links:

```python
# doc-coverage.py
import re
from pathlib import Path

def has_doc_link(file_path):
    """Check if file contains @doc annotations"""
    with open(file_path) as f:
        content = f.read()
    return '@doc' in content or '@api-doc' in content

# Calculate coverage
source_files = list(Path('src').rglob('*.py'))
with_docs = [f for f in source_files if has_doc_link(f)]
coverage = len(with_docs) / len(source_files) * 100

print(f"Documentation link coverage: {coverage:.1f}%")
```

### Reverse Link Tracking

Maintain reverse index in documentation:

```markdown
# Authentication Documentation

## Referenced By

This document is referenced by the following code files:

- `src/services/AuthenticationService.ts:15` - Main auth logic
- `src/middleware/auth.ts:34` - Auth middleware
- `src/routes/auth.ts:8` - Auth routes

<!-- AUTO-GENERATED: Do not edit manually -->
<!-- Generated by: scripts/update-doc-references.sh -->
```

## Link Maintenance

### Automated Updates

Git pre-commit hook to check doc links:

```bash
#!/bin/bash
# .git/hooks/pre-commit

echo "Validating documentation links..."

# Check for broken @doc links
broken_links=$(grep -r "@doc " src/ | while read -r line; do
  doc_path=$(echo "$line" | sed -n 's/.*@doc \([^[:space:]]*\).*/\1/p')
  file_path=$(echo "$doc_path" | cut -d'#' -f1)

  if [ ! -f "$file_path" ]; then
    echo "$line"
  fi
done)

if [ -n "$broken_links" ]; then
  echo "ERROR: Broken documentation links found:"
  echo "$broken_links"
  exit 1
fi
```

### Link Deprecation

Mark outdated links:

```typescript
/**
 * @doc docs/old-approach.md [DEPRECATED: See docs/new-approach.md]
 * @doc-current docs/new-approach.md
 *
 * This implementation is being migrated to new approach.
 * Old documentation kept for reference during transition.
 * Migration deadline: 2026-01-01
 */
```

### Versioned Documentation

Link to specific documentation versions:

```python
# @doc