From 2d8242d73744786dbcc05b00017d018632a91c83 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Nov 2025 15:43:49 +0000
Subject: [PATCH] Enhance documentation with Docusaurus features and fix
 accuracy issues

- Fix API reference: correct class names (PgsqlDatabase, DblibDatabase) and getCurrentVersion() return type
- Add Docusaurus frontmatter (title, description) to all documentation files
- Add Docusaurus admonitions (:::note, :::tip, :::warning, :::info) for better readability
- Improve documentation clarity with contextual warnings and tips
- Maintain sidebar_position order matching README.md (1-5)
- All docs follow Docusaurus markdown standards
---
 docs/api-reference.md     | 15 +++++++++++----
 docs/cli-usage.md         |  2 ++
 docs/database-setup.md    |  8 ++++++--
 docs/getting-started.md   |  6 +++++-
 docs/migration-scripts.md | 10 ++++++++++
 5 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/docs/api-reference.md b/docs/api-reference.md
index 1d1e275..b41b5f3 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 5
+title: API Reference
+description: Complete PHP API documentation for database migrations
 ---
 
 # API Reference
@@ -36,8 +38,9 @@ public function createVersion(): void
 // Check if database is versioned
 public function isDatabaseVersioned(): bool
 
-// Get current version
-public function getCurrentVersion(): int
+// Get current version and status
+// Returns: ['version' => int, 'status' => string]
+public function getCurrentVersion(): array
 
 // Update version table structure
 public function updateTableVersion(): void
@@ -124,9 +127,9 @@ interface DatabaseInterface
 ### Built-in Handlers
 
 - `MySqlDatabase`: MySQL/MariaDB
-- `PostgresDatabase`: PostgreSQL
+- `PgsqlDatabase`: PostgreSQL
 - `SqliteDatabase`: SQLite
-- `SqlServerDatabase`: Microsoft SQL Server
+- `DblibDatabase`: Microsoft SQL Server (both dblib and sqlsrv)
 
 ## Examples
 
@@ -155,6 +158,10 @@ $migration->addCallbackProgress(function ($action, $version, $fileInfo) {
 
 ### With Transaction Support
 
+:::note Transaction Support
+Transaction support is not available for MySQL as it doesn't support DDL commands inside transactions. The setting will be silently ignored for MySQL databases.
+:::
+
 ```php
 $migration
     ->withTransactionEnabled(true)
diff --git a/docs/cli-usage.md b/docs/cli-usage.md
index 64b6b8a..06623b3 100644
--- a/docs/cli-usage.md
+++ b/docs/cli-usage.md
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 4
+title: CLI Usage
+description: Command line interface guide for database migrations
 ---
 
 # Command Line Interface Usage
diff --git a/docs/database-setup.md b/docs/database-setup.md
index d96462a..27d49f2 100644
--- a/docs/database-setup.md
+++ b/docs/database-setup.md
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 2
+title: Database Setup
+description: Configure database connections for MySQL, PostgreSQL, SQLite, and SQL Server
 ---
 
 # Database Setup and Configuration
@@ -37,8 +39,10 @@ The library supports the following databases:
    ```
 
 4. Transaction Limitations:
-   - DDL statements not supported in transactions
-   - Transaction settings ignored for DDL
+
+:::warning MySQL Transaction Limitations
+MySQL does not support DDL (Data Definition Language) statements within transactions. Any transaction settings will be ignored for DDL operations like CREATE TABLE, ALTER TABLE, etc.
+:::
 
 ### PostgreSQL
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 2c62299..98f5a2f 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 1
+title: Getting Started
+description: Get started with PHP Database Migration - a framework-agnostic database versioning tool using pure SQL
 ---
 
 # Getting Started with PHP Database Migration
@@ -28,7 +30,9 @@ composer require "byjg/migration"
 composer require "byjg/migration-cli"
 ```
 
-For CLI usage, see [CLI documentation](cli-usage.md).
+:::tip
+For CLI usage, see the [CLI documentation](cli-usage.md) for detailed commands and options.
+:::
 
 ## Basic Usage
 
diff --git a/docs/migration-scripts.md b/docs/migration-scripts.md
index 719a965..d711853 100644
--- a/docs/migration-scripts.md
+++ b/docs/migration-scripts.md
@@ -1,5 +1,7 @@
 ---
 sidebar_position: 3
+title: Migration Scripts
+description: Learn how to write and organize database migration scripts
 ---
 
 # Writing Migration Scripts
@@ -23,6 +25,10 @@ The number represents the version that the script will migrate to (up) or from (
 
 ## Multi-Developer Workflow
 
+:::info Handling Multiple Developers
+When multiple developers work on different branches, use the `-dev` suffix to avoid version conflicts.
+:::
+
 When multiple developers work on different branches:
 
 1. Use `-dev` suffix for work in progress:
@@ -73,6 +79,10 @@ When multiple developers work on different branches:
 
 ### PostgreSQL-Specific Tips
 
+:::warning Important for PostgreSQL Functions
+Always add `--` comments after semicolons inside function definitions to prevent parsing errors.
+:::
+
 1. Use `--` after semicolons in functions:
    ```sql
    CREATE FUNCTION update_timestamp() RETURNS trigger AS $$