| name | documentation-linking |
| description | Use when creating bidirectional links between code and documentation. Covers link patterns, documentation references, context preservation across artifacts, and maintaining synchronization between code and docs. |
| allowed-tools | ["Read","Write","Edit","Bash","Grep","Glob"] |
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:
export class AuthenticationService {
}
Documentation → Code
Link from documentation to implementing code:
# 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
Relative Links
Line-Specific Links
Anchor Links
Documentation Types
Architecture Documentation
class UserService {
}
API Documentation
@app.post("/users")
async def create_user(user: UserCreate) -> User:
"""
@request-example:
POST /users
{
"email": "user@example.com",
"name": "John Doe"
}
@response-example:
201 Created
{
"id": 123,
"email": "user@example.com",
"name": "John Doe",
"created_at": "2025-12-04T10:00:00Z"
}
"""
Decision Records
public class CacheService {
}
Test Documentation
func TestUserRepository(t *testing.T) {
}
Runbook Links
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
"""
Cross-Referencing Patterns
Issue/Ticket References
class NotificationService {
}
Wiki/Confluence Links
class DataExtractor:
External Resources
pub struct JwtToken {
}
Synchronization Strategies
Automated Link Validation
Script to validate documentation links:
#!/bin/bash
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:
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
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:
# 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:
#!/bin/bash
echo "Validating documentation 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:
Versioned Documentation
Link to specific documentation versions:
class APIv2Handler:
Documentation Patterns
README Links
Link to README for module documentation:
package userservice
Example Code
Link to runnable examples:
pub struct Repository<T> {
}
Tutorial Links
export class SDK {
}
Anti-Patterns
Don't
❌ Use brittle relative links
❌ Link to outdated documentation
❌ Create circular documentation dependencies
Do
✅ Use repository-relative paths
✅ Keep links current
✅ Create clear navigation hierarchy
Integration Examples
Markdown Documentation
# User Service
## Implementation
The user service is implemented across several files:
### Core Logic
- [`src/services/UserService.ts`](../src/services/UserService.ts) - Main service class
- [`src/models/User.ts`](../src/models/User.ts) - User model
- [`src/repositories/UserRepository.ts`](../src/repositories/UserRepository.ts) - Data access
### API Layer
- [`src/routes/users.ts`](../src/routes/users.ts#L15-L45) - REST endpoints
- [`src/controllers/UserController.ts`](../src/controllers/UserController.ts) - Request handling
### Tests
- [`tests/unit/UserService.test.ts`](../tests/unit/UserService.test.ts) - Unit tests
- [`tests/integration/users.test.ts`](../tests/integration/users.test.ts) - Integration tests
OpenAPI/Swagger
paths:
/users:
post:
summary: Create user
description: |
Creates a new user in the system.
**Implementation:**
- Handler: `src/handlers/users.go:CreateUser`
- Validation: `src/validators/user.go:ValidateCreate`
- Database: `src/repositories/user_repo.go:Insert`
**Related Documentation:**
- [User Management Guide](../docs/user-management.md)
- [API Authentication](../docs/api-auth.md)
JSDoc/TypeDoc
export class AuthService {
}
Related Skills
- notetaker-fundamentals
- code-annotation-patterns
Resources
