26

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

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

4

3 回答 3

21

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

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

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

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

于 2015-10-05T12:51:30.127 回答
6

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

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

  • 功能名称、简短描述和用途
  • 参数和返回值列表，带有描述
  • 所有副作用的列表（例如，变量或文件的更改）
于 2012-05-11T14:22:45.800 回答
2

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

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