Menu
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?
378
One of the many known methods to exit a bash script while writing is the simple shortcut key, i.e., “Ctrl+X”. While at run time, you can exit the code using “Ctrl+Z”.
The [[ ... ]] part allows to test a condition using operators. Think of it as an if statement. In your example, you're using the -s operator, which tests that the referenced file is not empty.
Normally, a Bash script file has . sh extension to make it clear that it is a shell script file.
sh extension on your bash scripts.
The best bash style guide I have come across is from Google. There is also some additional advice from the Chromium project. For learning bash, the Apple Developer Shell Scripting primer is excellent. Using a style guide for bash is rather sensible, as it is full of tricks and unexpected and difficult to diagnose quirks.
For learning bash, the Apple Developer Shell Scripting primer is excellent. Using a style guide for bash is rather sensible, as it is full of tricks and unexpected and difficult to diagnose quirks. Thus, if you follow the same style all the time, you should only fall for each of those tricks once.
The Bash manual page should be used as the definitive reference on shell behavior. An introduction to the shell. Some definitions used in the rest of this manual. The shell "building blocks". Commands that are a part of the shell. Variables used or set by Bash.
You're browsing the Bash documentation. To browse all docs, go to devdocs.io (or press esc ). 1.1 What is Bash? 1.2 What is a shell? 6.3.1 What is an Interactive Shell?
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.
140
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:
22
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
