Add a reason directive to document why some checks were disabled

[NickLarsenNZ]

For new checks and feature suggestions

• [ ] https://www.shellcheck.net/ (i.e. the latest commit) currently gives no useful warnings about this
• [x] I searched through https://github.com/koalaman/shellcheck/issues and didn't find anything related

Here's a snippet or screenshot that shows the problem:

#!/bin/bash

function blah {
  echo hello $1
}

# shellcheck disable=SC2044 - we call a local function which is not available when using find with -exec
for archive in $(find "$targetdir" -name '*.tar.gz'); do
  blah "$archive"
done

Here's what shellcheck currently says:

In shared/log4shell.sh line 113:
  # shellcheck disable=SC2044 - we call a local function which is not available when using find with -exec
  ^-- SC1073 (error): Couldn't parse this shellcheck directive. Fix to allow more checks.
                               ^-- SC1072 (error): Expected '=' after directive key. Fix any mentioned problems and try again.

Here's what I wanted or expected to see:

I would like there to be a reason directive so we can document why we disable some checks. Eg:

# shellcheck disable=SC2044 reason="we call a local function which is not available when using find with -exec"

[NickLarsenNZ]

Closing, as this is possible, just not documented from what I can see.

For anyone trying to do the same, you can do it like so:

# shellcheck disable=SC1234 # here goes the reason