【发布时间】：2012-05-11 14:17:00
【问题描述】：
我目前正在编写一个包含许多函数的 Bash 脚本，并希望添加文档以使其他团队成员了解该函数的意义。
是否有用于记录 Bash 脚本及其包含的函数的标准“样式”？
【问题讨论】：
标签： linux bash shell documentation
【发布时间】：2012-05-11 14:17:00
【问题描述】：
我知道我正在添加一个旧问题的答案，但我觉得工具最近有所改进，并希望提供更多建议以帮助其他查看此问题的人。
我最近发现了TomDoc.sh，它在shell 脚本中使用了TomDoc 样式的cmets。然后提供的工具可以提取信息并生成降价或纯文本文档。
还存在其他工具。 BashDoc 仿照 JavaDoc 语法，支持多种标签。使用RoboDoc，您可以在 Bash 代码中嵌入 C 风格的注释，它会提取必要的信息。最后，Apple 使用HeaderDoc 编写其 shell 脚本。所有这三个都为您编写的 cmets 提供了建议的样式。
如果您希望对代码进行注释而不是生成文档，shocco.sh 可能是您的首选。它没有特定的格式，旨在让您查看描述您正在运行的 shell 命令的人类可读文本。
【讨论】：
-
啊，互联网。这是在 bashdoc 链接的底部：“2004 年 3 月 3 日 - 决赛糟透了。还有更多的工作，所以如果我还剩下一个的话，这将被搁置。:) 可能是一两个星期。” 12.5 年后，有更新吗？
通常，我会尝试遵循类似于我在其他语言（如 C）中使用的指南。
这包括一个函数头，其中包含：
- 函数名称、简短描述和用途
- 参数和返回值列表以及说明
- 所有副作用的列表（例如，变量或文件的更改）
【讨论】：
据我了解，Bash 文档没有标准。 但通常你会：
- 在您的 bash 文件中包含一个标头，其中包含您的姓名、版权、 联系方式，并简要说明脚本的作用
- usage() 函数 解释如何启动和使用你的函数。
- 顶部的评论 每个函数来解释 func 的作用。
【讨论】：