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

Question

我目前正在编写一个Bash脚本,其中包含许多函数,并希望添加文档以使其他团队成员了解函数的重点.

是否有标准的"样式"来记录Bash脚本及其包含的功能？

Answer 1

我知道我正在添加一个旧问题的答案,但我觉得工具最近有所改进,并希望提供其他建议,以帮助其他正在查看此问题的人.

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

其他工具也存在. BashDoc以JavaDoc语法为模型,支持各种标记.使用RoboDoc,您可以在Bash代码中嵌入C风格的注释,并提取必要的信息.最后,Apple使用HeaderDoc进行shell脚本编写.所有这三个都为您编写的注释提供了建议的样式.

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

Answer 2

通常,我会尝试遵循与我使用的其他语言(例如C)类似的指南.

这包括一个函数头,包含:

• 功能名称,简短描述和目的
• 参数列表和返回值,以及描述
• 所有副作用的列表(例如,变量或文件的变化)