[TASK] Create Logging System Documentation and Examples

[johnnyt]

Task Description

Create comprehensive documentation for the new logging system, including API documentation, usage examples, migration guide, and CHANGELOG updates.

Acceptance Criteria

• Complete API documentation for all logging modules
• Usage examples showing common logging patterns
• Migration guide from old Logger usage
• Update CHANGELOG.md with logging system changes
• Add configuration examples to README (if applicable)
• Document best practices for logging in SCXML actions

Implementation Plan

1. Add comprehensive module documentation to all logging modules
2. Create usage examples for common scenarios
3. Write migration guide for existing codebases
4. Update CHANGELOG.md with detailed feature description
5. Add logging section to main documentation
6. Review and improve all docstrings

Documentation Areas

API Documentation

• Statifier.Logging.Adapter protocol with examples
• Statifier.Logging.LogManager with all convenience functions
• Statifier.Logging.ElixirLoggerAdapter configuration options
• Statifier.Logging.TestAdapter usage in tests
• StateChart logging field documentation

Usage Examples

Basic Usage

# Production logging
{:ok, state_chart} = Interpreter.initialize(document)
state_chart = LogManager.info(state_chart, "Starting process", %{
  action_type: "initialization"
})

Test Usage

# Test logging
{:ok, state_chart} = Interpreter.initialize(document)
state_chart = LogManager.debug(state_chart, "Debug info", %{
  action_type: "test"
})

# Inspect logs
assert [%{level: :debug, message: "Debug info"}] = state_chart.logs

Custom Configuration

{:ok, state_chart} = Interpreter.initialize(document, [
  log_adapter: {Statifier.Logging.TestAdapter, [max_entries: 50]},
  log_level: :trace
])

Migration Guide

Document how to migrate from:

# Old way
Logger.info("Event processed")

# New way  
state_chart = LogManager.info(state_chart, "Event processed", %{
  action_type: "event_processing"
})

CHANGELOG Entry

Add comprehensive entry to CHANGELOG.md under "Unreleased" section:

Enhanced Logging System

• Flexible Logging Architecture: New adapter-based logging system
• Multiple Adapters: ElixirLoggerAdapter and TestAdapter built-in
• Automatic Metadata: LogManager extracts current_state and event automatically
• Test-Friendly: TestAdapter provides clean test output
• Configuration: Support for application and runtime configuration

Dependencies

• Depends on: Issue Add CI pipeline and commit linting #1 (Core Logging Infrastructure)
• Depends on: Issue Adds CI pipeline and commit linting #2 (Configuration System)
• Depends on: Issue Add spec folder #3 (Migrate Logger Calls)
• Depends on: Issue Add README and LICENSE #4 (Test Integration)

Files to Modify

• All logging modules: Add/improve @moduledoc and @doc
• CHANGELOG.md - Add comprehensive logging system entry
• documentation/LOGGING_ARCHITECTURE_PLAN.md - Mark as implemented
• Create documentation/LOGGING_USAGE_EXAMPLES.md
• Create documentation/LOGGING_MIGRATION_GUIDE.md

Testing Requirements

• All documentation examples are tested and work correctly
• ExDoc generates clean documentation
• Code examples in docs are syntactically correct

Documentation

• Complete API reference for all public functions
• Real-world usage examples
• Configuration reference
• Migration guide for existing users
• Best practices guide

References

• Original design doc: /documentation/LOGGING_ARCHITECTURE_PLAN.md
• All previous logging implementation issues