docs: enhance documentation for .roo directory functions with detailed examples and usage

Author: samhvw8

src/services/roo-config/index.ts

@@ -4,8 +4,24 @@ import fs from "fs/promises"
 
 /**
  * Gets the global .roo directory path based on the current platform
- * macOS/Linux: ~/.roo/
- * Windows: %USERPROFILE%\.roo\
+ *
+ * @returns The absolute path to the global .roo directory
+ *
+ * @example Platform-specific paths:
+ * ```
+ * // macOS/Linux: ~/.roo/
+ * // Example: /Users/john/.roo
+ *
+ * // Windows: %USERPROFILE%\.roo\
+ * // Example: C:\Users\john\.roo
+ * ```
+ *
+ * @example Usage:
+ * ```typescript
+ * const globalDir = getGlobalRooDirectory()
+ * // Returns: "/Users/john/.roo" (on macOS/Linux)
+ * // Returns: "C:\\Users\\john\\.roo" (on Windows)
+ * ```
  */
 export function getGlobalRooDirectory(): string {
 	const homeDir = os.homedir()
@@ -14,6 +30,32 @@ export function getGlobalRooDirectory(): string {
 
 /**
  * Gets the project-local .roo directory path for a given cwd
+ *
+ * @param cwd - Current working directory (project path)
+ * @returns The absolute path to the project-local .roo directory
+ *
+ * @example
+ * ```typescript
+ * const projectDir = getProjectRooDirectoryForCwd('/Users/john/my-project')
+ * // Returns: "/Users/john/my-project/.roo"
+ *
+ * const windowsProjectDir = getProjectRooDirectoryForCwd('C:\\Users\\john\\my-project')
+ * // Returns: "C:\\Users\\john\\my-project\\.roo"
+ * ```
+ *
+ * @example Directory structure:
+ * ```
+ * /Users/john/my-project/
+ * ├── .roo/                    # Project-local configuration directory
+ * │   ├── rules/
+ * │   │   └── rules.md
+ * │   ├── custom-instructions.md
+ * │   └── config/
+ * │       └── settings.json
+ * ├── src/
+ * │   └── index.ts
+ * └── package.json
+ * ```
  */
 export function getProjectRooDirectoryForCwd(cwd: string): string {
 	return path.join(cwd, ".roo")
@@ -71,8 +113,36 @@ export async function readFileIfExists(filePath: string): Promise<string | null>
 
 /**
  * Gets the ordered list of .roo directories to check (global first, then project-local)
+ *
  * @param cwd - Current working directory (project path)
  * @returns Array of directory paths to check in order [global, project-local]
+ *
+ * @example
+ * ```typescript
+ * // For a project at /Users/john/my-project
+ * const directories = getRooDirectoriesForCwd('/Users/john/my-project')
+ * // Returns:
+ * // [
+ * //   '/Users/john/.roo',           // Global directory
+ * //   '/Users/john/my-project/.roo' // Project-local directory
+ * // ]
+ * ```
+ *
+ * @example Directory structure:
+ * ```
+ * /Users/john/
+ * ├── .roo/                    # Global configuration
+ * │   ├── rules/
+ * │   │   └── rules.md
+ * │   └── custom-instructions.md
+ * └── my-project/
+ *     ├── .roo/                # Project-specific configuration
+ *     │   ├── rules/
+ *     │   │   └── rules.md     # Overrides global rules
+ *     │   └── project-notes.md
+ *     └── src/
+ *         └── index.ts
+ * ```
  */
 export function getRooDirectoriesForCwd(cwd: string): string[] {
 	const directories: string[] = []
@@ -88,9 +158,54 @@ export function getRooDirectoriesForCwd(cwd: string): string[] {
 
 /**
  * Loads configuration from multiple .roo directories with project overriding global
+ *
  * @param relativePath - The relative path within each .roo directory (e.g., 'rules/rules.md')
  * @param cwd - Current working directory (project path)
  * @returns Object with global and project content, plus merged content
+ *
+ * @example
+ * ```typescript
+ * // Load rules configuration for a project
+ * const config = await loadConfiguration('rules/rules.md', '/Users/john/my-project')
+ *
+ * // Returns:
+ * // {
+ * //   global: "Global rules content...",     // From ~/.roo/rules/rules.md
+ * //   project: "Project rules content...",   // From /Users/john/my-project/.roo/rules/rules.md
+ * //   merged: "Global rules content...\n\n# Project-specific rules (override global):\n\nProject rules content..."
+ * // }
+ * ```
+ *
+ * @example File paths resolved:
+ * ```
+ * relativePath: 'rules/rules.md'
+ * cwd: '/Users/john/my-project'
+ *
+ * Reads from:
+ * - Global: /Users/john/.roo/rules/rules.md
+ * - Project: /Users/john/my-project/.roo/rules/rules.md
+ *
+ * Other common relativePath examples:
+ * - 'custom-instructions.md'
+ * - 'config/settings.json'
+ * - 'templates/component.tsx'
+ * ```
+ *
+ * @example Merging behavior:
+ * ```
+ * // If only global exists:
+ * { global: "content", project: null, merged: "content" }
+ *
+ * // If only project exists:
+ * { global: null, project: "content", merged: "content" }
+ *
+ * // If both exist:
+ * {
+ *   global: "global content",
+ *   project: "project content",
+ *   merged: "global content\n\n# Project-specific rules (override global):\n\nproject content"
+ * }
+ * ```
  */
 export async function loadConfiguration(
 	relativePath: string,
@@ -134,4 +249,4 @@ export async function loadConfiguration(
 }
 
 // Export with backward compatibility alias
-export const loadRooConfiguration = loadConfiguration
+export const loadRooConfiguration: typeof loadConfiguration = loadConfiguration