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.