Linux Shell函数帮助说明靠注释约定：函数上方写#注释说明功能、参数及示例；或函数内用case判断-h/--help参数并输出帮助后return 0。
在 Linux Shell 脚本中，为函数添加帮助说明不是靠内置语法，而是靠约定俗成的实践方式：把说明文字写在函数定义上方或内部注释里，并提供一个显式调用入口（比如 help 或 -h 参数）来展示它。
把帮助文本写在函数上方作为注释
这是最常见、最轻量的做法。用 # 注释逐行说明函数用途、参数含义和用法示例：
- 注释要贴近函数定义，保持可读性
- 建议包含：功能简述、参数说明（如
$1是什么）、典型调用方式 - 示例：
# backup_file() —— 将指定文件备份为 filename.bak
# 参数：
# $1: 待备份的源文件路径（必填）
# 用法示例：
# backup_file /etc/hosts
backup_file() {
[ -z "$1" ] && { echo "错误：缺少源文件路径"; return 1; }
[ ! -f "$1" ] && { echo "错误：'$1' 不存在或不是普通文件"; return 1; }
cp "$1" "$1.bak"
echo "已备份为 $1.bak"
}在函数内部支持 -h 或 --help 参数
让函数本身能响应帮助请求，更接近命令行工具体验。关键是在开头判断参数并提前退出：
- 用
case "$1" in检查第一个参数是否为帮助标识 - 匹配时直接输出帮助信息并用
return 0退出，不执行后续逻辑 - 示例：
deploy_app() {
case "$1" in
-h|--help)
cat << 'EOF'
部署应用到指定环境
用法：deploy_app <环境名> [版本号]
<环境名>：prod | staging | dev（必填）
[版本号]：Git commit ID 或标签，默认为 main 分支
示例：
deploy_app prod v2.4.1
deploy_app dev
EOF
return 0
;;
esac
<p>local env="$1"
local version="${2:-main}"
[ -z "$env" ] && { echo "错误：请指定环境名"; return 1; }</p><h1>…… 实际部署逻辑</h1><p>}统一管理帮助信息：用专用 help 函数
当脚本含多个函数时，集中维护帮助内容更清晰。定义一个 show_help，再在主流程中响应 -h：
- 主函数（如
main）检查全局参数 -
show_help中用printf或cat <<EOF格式化输出 - 所有函数的帮助整合在一起，避免碎片化
- 示例节选：
show_help() {
printf "用法：$0 [选项]\n\n"
printf "选项：\n"
printf " -h, --help 显示此帮助信息\n"
printf " -v, --version 显示版本号\n"
printf " backup FILE 备份单个文件\n"
printf " sync DIR 同步目录到远程服务器\n\n"
printf "示例：\n $0 backup /var/log/syslog\n"
}
<p>main() {
case "$1" in
-h|--help) show_help; exit 0 ;;
backup) shift; backup_file "$@"; exit $? ;;
sync) shift; sync_dir "$@"; exit $? ;;
*) echo "未知命令：$1"; show_help; exit 1 ;;
esac
}
main "$@"小技巧：让帮助信息可被自动提取
如果希望将来用工具生成文档，可在注释中加标记，例如：
- 以
##开头的行作为文档行（类似 Python 的 docstring） - 写个简单解析脚本提取所有
##行，拼成 README 片段 - 不影响函数运行，纯文本约定
## send_email() —— 发送纯文本邮件
## 参数：
## $1: 收件人邮箱
## $2: 邮件主题
## $3: 邮件正文
send_email() {
echo "$3" | mail -s "$2" "$1"
}不复杂但容易忽略
