# Function Documentation Template

## Required Doc Block Format

Every function MUST have this header (缺一不可):

```bash
### <One-line功能描述，动词开头>
### @param <param_name> <type> <用途说明>
### @param <param_name> <type> <用途说明>
### @return <exit_code> <状态描述>
### @require <依赖项/命令/权限/环境变量>
### @side_effect <对文件/网络/系统的影响> (可选，有副作用时必填)
function_name() {
    local param1="$1"
    local param2="${2:-default}"

    # Implementation
}
```

## Type Annotations

| Type | Description | Example |
|------|-------------|---------|
| `string` | Any text | `@param name string User's name` |
| `int` | Integer number | `@param count int Number of retries` |
| `bool` | true/false | `@param verbose bool Enable verbose mode` |
| `path` | File/directory path | `@param config path Path to config file` |
| `array` | Bash array | `@param files array List of input files` |
| `fd` | File descriptor | `@param logfd fd File descriptor for logging` |

## Complete Example

```bash
### Validate that a file exists and is readable
### @param file_path path Absolute or relative path to validate
### @param allow_empty bool Whether empty files are valid (default: false)
### @return 0 File is valid and readable
### @return 1 File does not exist
### @return 2 File is not readable
### @return 3 File is empty (when allow_empty=false)
### @require read permission on file_path
validate_file() {
    local file_path="$1"
    local allow_empty="${2:-false}"

    # > Check existence first (most common failure)
    if [[ ! -e "$file_path" ]]; then
        log_error "File not found: $file_path"
        return 1
    fi

    # > Check readability
    if [[ ! -r "$file_path" ]]; then
        log_error "File not readable: $file_path"
        return 2
    fi

    # > Check empty (only if not allowed)
    if [[ "$allow_empty" != "true" && ! -s "$file_path" ]]; then
        log_error "File is empty: $file_path"
        return 3
    fi

    return 0
}
```

## Logging Functions Template

```bash
### Log message at DEBUG level
### @param message string Message to log
### @return 0 Always succeeds
log_debug() {
    [[ "${LOG_LEVEL:-INFO}" == "DEBUG" ]] || return 0
    printf '[%s] [DEBUG] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" >&2
}

### Log message at INFO level
### @param message string Message to log
### @return 0 Always succeeds
log_info() {
    [[ "${LOG_LEVEL:-INFO}" =~ ^(DEBUG|INFO)$ ]] || return 0
    printf '[%s] [INFO] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" >&2
}

### Log message at WARN level
### @param message string Message to log
### @return 0 Always succeeds
log_warn() {
    [[ "${LOG_LEVEL:-INFO}" =~ ^(DEBUG|INFO|WARN)$ ]] || return 0
    printf '[%s] [WARN] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" >&2
}

### Log message at ERROR level
### @param message string Message to log
### @return 0 Always succeeds
log_error() {
    printf '[%s] [ERROR] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*" >&2
}
```

## Die Function Template

```bash
### Exit with error message and code, including location info
### @param message string Error message
### @param exit_code int Exit code (default: 1)
### @return never Returns (exits script)
### @side_effect Terminates script execution
die() {
    local message="$1"
    local exit_code="${2:-1}"
    local caller_info=""

    # > Build stack trace for debugging
    if [[ "${BASH_LINENO[0]:-0}" -gt 0 ]]; then
        caller_info=" (${FUNCNAME[1]:-main}:${BASH_LINENO[0]:-?})"
    fi

    log_error "${message}${caller_info}"
    exit "$exit_code"
}
```

## Run Command Wrapper Template

```bash
### Execute command with dry-run support and error handling
### @param cmd string Command to execute (as array: "${cmd[@]}")
### @return 0 Command succeeded
### @return 1 Command failed
### @side_effect Executes external command (unless DRY_RUN=true)
run_cmd() {
    local -a cmd=("$@")

    if [[ "${DRY_RUN:-false}" == "true" ]]; then
        log_info "[DRY-RUN] Would execute: ${cmd[*]}"
        return 0
    fi

    if [[ "${VERBOSE:-false}" == "true" ]]; then
        log_debug "Executing: ${cmd[*]}"
    fi

    if ! "${cmd[@]}"; then
        log_error "Command failed: ${cmd[*]}"
        return 1
    fi

    return 0
}
```

## Input Validation Pattern

```bash
### Validate path argument
### @param path path Path to validate
### @param must_exist bool Path must exist (default: true)
### @param must_be_writable bool Path must be writable (default: false)
validate_path() {
    local path="$1"
    local must_exist="${2:-true}"
    local must_be_writable="${3:-false}"

    # > Reject empty paths
    [[ -n "$path" ]] || die "Path cannot be empty" 2

    # > Resolve to absolute path
    if [[ "$path" != /* ]]; then
        path="$(cd "$(dirname "$path")" 2>/dev/null && pwd)/$(basename "$path")"
    fi

    if [[ "$must_exist" == "true" && ! -e "$path" ]]; then
        die "Path does not exist: $path" 5
    fi

    if [[ "$must_be_writable" == "true" && ! -w "$path" ]]; then
        die "Path not writable: $path" 4
    fi

    printf '%s' "$path"
}
```
