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

What is the standard for documentation style in Bash scripts?

提问by linusthe3rd

I am currently writing a Bash script that has a number of functions in it and would like to add docs to make other team members understand what the point of the function is.

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

Is there a standard "style" for documenting Bash scripts and the functions it contains?

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

采纳答案by mouviciel

Usually, I try to follow guidelines that are analog to the ones I use with other languages like C.

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

This includes a function header containing:

这包括一个包含以下内容的函数头：

• function name, short description and purpose
• list of arguments and return values, with descriptions
• list of all side effects (e.g., changes in variables or files)

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

回答by fidian

I do understand I'm adding an answer to an old question, but I feel the tooling has improved lately and would like to give additional suggestions in order to help out others who are viewing this question.

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

I have recently found TomDoc.sh, which uses TomDoc style comments in shell scripts. The tool provided can then extract information and generate markdown or plain text documents.

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

Other tools also exist. BashDocis modeled after the JavaDoc syntax, supporting a variety of tags. With RoboDocyou embed a C-style comment in your Bash code and it extracts the necessary information. Lastly, Apple uses HeaderDocfor its shell scripting. All three of these have a suggested style for the comments that you write.

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

If you wish to annotate your code more than generate documentation, shocco.shmay be what you'd prefer. It doesn't have a specific format and is designed for you to see human-readable text describing the shell commands that you are running.

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

回答by user1383162

To my understanding there is no standard for Bash doc. But typically you would:

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

• include a header to your bash file, with your name, copyright, contact, and briefly what the script does
• a usage() function that explains how to launch and use your function.
• a comment at the top of each function to explain what the func does.

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