What is the standard documentation style for Bash scripts?

Question

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

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

Answer 1

I usually try to follow recommendations that are analogous to those that I use with other languages ​​such as C.

This includes a function header containing:

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

Answer 2

I understand that I am adding the answer to the old question, but I feel that the tool has improved recently and would like to give additional suggestions to help others who are considering this question.

I recently found TomDoc.sh that uses TomDoc style comments in shell scripts. Then the provided tool can extract information and create markdowns or text documents.

There are other tools. BashDoc is modeled after a JavaDoc syntax that supports multiple tags. With RoboDoc, you insert a C-style comment into your Bash code and extract the necessary information. Finally, Apple uses HeaderDoc for its shell scripts. All three of them have a recommended style for the comments you write.

If you want to comment on your code more than generate documentation, shocco.sh may be what you would prefer. It does not have a specific format and is designed to view human-readable text describing shell commands that you execute.

Answer 3

As far as I understand, there is no standard for Bash doc. But usually you would:

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