linux - Bash 脚本中文档样式的标准是什么？

Question

我目前正在编写一个包含许多函数的 Bash 脚本，并希望添加文档以使其他团队成员了解该函数的意义。

是否有用于记录 Bash 脚本及其包含的功能的标准“样式”？

Answer 1

我确实知道我正在添加一个旧问题的答案，但我觉得工具最近有所改进，并想提供更多建议以帮助其他正在查看此问题的人。

我最近发现了 TomDoc.sh，它在 shell 脚本中使用了 TomDoc 样式的注释。然后提供的工具可以提取信息并生成降价或纯文本文档。

其他工具也存在。 BashDoc仿照 JavaDoc 语法，支持多种标签。使用RoboDoc，您可以在 Bash 代码中嵌入 C 风格的注释，它会提取必要的信息。最后，Apple 将HeaderDoc用于其 shell 脚本。所有这三个都为您撰写的评论提供了建议的样式。

如果您希望对代码进行注释而不是生成文档，那么 shocco.sh可能是您更喜欢的。它没有特定的格式，旨在让您查看描述您正在运行的 shell 命令的人类可读文本。

Answer 2

通常，我会尝试遵循类似于我在其他语言（如 C）中使用的指南。

这包括一个函数头，其中包含：

• 功能名称、简短描述和用途
• 参数和返回值列表，带有描述
• 所有副作用的列表（例如，变量或文件的更改）

Answer 3

据我了解，Bash 文档没有标准。但通常你会：

• 在您的 bash 文件中包含一个标头，其中包含您的姓名、版权、联系方式以及脚本的简要功能
• 一个 usage() 函数，它解释了如何启动和使用你的函数。
• 每个函数顶部的注释以解释 func 的作用。