Wesley Dean
>

Bash Shell Script Usage Generation based on Doxygen Comments

3 min read

In a post on Documentation and AI , I advocated for the use of Doxygen-style comments when developing and maintaining shell scripts to preserve intent, contracts, interfaces, edge-cases, and context information. An AI wouldn't need to reinterpret how a block of Bash shell script code worked every time it ran. Doing so would provide a pathway by which subtle changes in understanding could be introduced, much like what happens in a telephone game.

Another benefit of that structured documentation technique is the ability to generate usage information for shell scripts. This allows you to automatically generate what is displayed when someone runs your_script.bash --help without having to maintain that help screen yourself.

So, I put together a tool that can accept one or more Bash shell scripts as inputs, generate the help text, and then inject that help text back into the script. Along the way, the incoming Bash shell scripts are minimized so that the finished version is tighter and no longer carries the full volume of inline documentation.

Since my scripts typically have two lines of comments for every line of code, this results in shipped scripts having about one-third the size of the heavily-documented versions.

This tooling -- which can be run via Docker or installed directly -- is intended for use in a CI/CD setting. I write something in my_script.src.bash and it produces my_script.bash when a commit is pushed to the upstream repository.

The tool can be found on GitHub at wesley-dean/bash_usage_help_generator or on DockerHub at wesleydean/bash_usage_help_generator

Full Example

This is an example of how the tool works.

Input: example.src.bash

#!/usr/bin/env bash

## @file example.src.bash
## @brief Example CLI tool
## @details
## This script demonstrates usage help generation.
##
while getopts "h" option ; do
  case "$option" in
    h) usage_help ; exit 0 ;; ##- display usage help
  esac
done

printf 'Hello\n'

Run

bash_usage_help_generator.bash example.src.bash

Output: example.bash

#!/usr/bin/env bash
## @cond GENERATED_USAGE_HELP
usage_help() {
  cat <<'__BASHLIB_USAGE_HELP__'
## Usage

`example.bash` [-h]

# file example.src.bash

## Brief

Example CLI tool

## Details

This script demonstrates usage help generation.

## Options

* `-h`: display usage help

__BASHLIB_USAGE_HELP__
}
## @endcond
while getopts "h" option ; do case "$option" in h) usage_help ; exit 0 ;;esac;done;printf 'Hello\n';

Explanation

The tool takes the original script, example.src.bash, extracts the comments, and then writes example.bash to the same directory as example.src.bash. The written file is minified -- which isn't very obvious in this example -- and has the help text injected near the top of the script.

Resources

I also recommend adding the following to your Bash shell scripting pipelines:

Tags