majiayu000 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:
/**
* 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:
# 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
# @doc /docs/database/migrations.md#schema-versioning
# Full path from repository root
Relative Links
// @doc ../../../docs/api/rest-endpoints.md#user-endpoints
// Relative to current file
Line-Specific Links
// @impl service/user_service.go:145-178
// Links to specific line range
Anchor Links
/// @doc architecture.md#data-flow-diagram
/// Links to specific section via anchor
Documentation Types
Architecture Documentation
/**
* @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
# @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": "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"
}
"""
# Implementation
Decision Records
/**
* @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
// @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
# @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
/**
* @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
# @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
/// @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:
#!/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:
# 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:
# 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
# .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:
/**
* @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:
# @doc docs/v2/api-reference.md
# @doc-version 2.3.0
#
# This code implements API v2.3.0 specification.
# For v3.0.0 changes, see docs/v3/migration-guide.md
class APIv2Handler:
# Implementation
Documentation Patterns
README Links
Link to README for module documentation:
// @readme ./README.md
//
// Package userservice provides user management functionality.
// See README.md for usage examples and configuration options.
package userservice
Example Code
Link to runnable examples:
/// @example examples/basic-usage.rs
/// @example-advanced examples/advanced-patterns.rs
///
/// Basic usage example shows simple CRUD operations.
/// Advanced example demonstrates batching and transactions.
pub struct Repository<T> {
// Implementation
}
Tutorial Links
/**
* @tutorial docs/tutorials/getting-started.md
* @tutorial-video https://youtube.com/watch?v=abc123
* @interactive-demo https://demo.example.com
*
* New to this library? Start with the getting started tutorial.
* Video walkthrough available for visual learners.
*/
export class SDK {
// Implementation
}
Anti-Patterns
Don't
❌ Use brittle relative links
# @doc ../../../../../../../docs/guide.md
# Bad - breaks easily when files move
❌ Link to outdated documentation
// @doc docs/deprecated-api.md
// Bad - should link to current docs or mark as deprecated
❌ Create circular documentation dependencies
// file1.go
// @doc docs/file2.md
// docs/file2.md references file3.go
// file3.go references file1.go
// Bad - circular reference makes navigation confusing
Do
✅ Use repository-relative paths
# @doc docs/guide.md
# Good - stable even if current file moves
✅ Keep links current
// @doc docs/current-api.md
// @doc-history docs/api-v1.md [DEPRECATED]
// Good - clear which is current
✅ Create clear navigation hierarchy
// @doc-parent docs/architecture/overview.md
// @doc-current docs/architecture/auth-service.md
// @doc-related docs/architecture/user-service.md
// Good - clear hierarchy and relationships
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
# api/openapi.yaml
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
/**
* User authentication service
*
* @see {@link ../docs/architecture/auth-flow.md} for authentication flow diagram
* @see {@link ../docs/api/auth-api.md} for API documentation
*
* @example
* ```typescript
* const auth = new AuthService();
* const token = await auth.login(username, password);
* ```
*
* @example
* See {@link ../examples/auth-flow.ts} for complete authentication example
*/
export class AuthService {
// Implementation
}
Related Skills
- notetaker-fundamentals
- code-annotation-patterns