What is the standard for documentation style in Bash scripts?

Question

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.

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

`man` pages for formatting and examples of style: https://unix.stackexchange.com/questions/6891/how-can-i-add-man-page-entries-for-my-own-power-tools — Anton Tarasenko, Oct 23 '17 at 21:01

score 23 · Answer 1 · edited Mar 29 '17 at 11:08

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.

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

If you wish to annotate your code more than generate documentation, shocco.sh may 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.

Ah, internet. This is at the bottom of the bashdoc link: "3 Mar 2004 - Finals suck. And there's lots more work too, so this is going to the back burner, if I've still got one of those left. :) Probably for a week or two." 12.5 years later, any updates? — JDS, Oct 19 '16 at 16:32

score 6 · Accepted Answer · answered May 11 '12 at 14:22

Usually, I try to follow guidelines that are analog to the ones I use with other languages like 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)

score 2 · Answer 3 · answered May 11 '12 at 14:31

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

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.

What is the standard for documentation style in Bash scripts?

3 Answers3