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 doc没有标准。 但通常你会：

• 在您的bash文件中加入一个标题，包含您的姓名，版权， 联系，简要说明脚本的作用
• 一个usage（）函数 解释了如何启动和使用您的功能。
• 顶部的评论 每个函数来解释func的作用。