Initial pass at docs for formatters

[ZacSweers]

No description provided.

[github-actions]

1. The code could benefit from better organization and structure. It would be helpful to break it down into smaller functions or methods that have specific responsibilities. This would make the code easier to read, understand, and maintain.

2. The code could use more descriptive variable and function names. This would make it easier to understand what each variable and function is used for.

3. The code could benefit from error handling and logging. Currently, if an error occurs, the code simply exits without providing any information about the error. It would be helpful to log the error message and provide more context to the user.

4. The code could be improved by using more modern and concise syntax. For example, instead of using [[ ! -z ${kts_files_list} ]], you can use [[ -n ${kts_files_list} ]] to check if the variable is not empty.

5. The code could be improved by using more efficient and readable constructs. For example, instead of using grep -oE '[^ ]+$' to extract filenames, you can use basename to get the base name of a file.

Here are some specific changes that can be made to improve the code:

1. Extract the logic for sorting dependencies into a separate function. This will make the code more modular and easier to understand.

function sort_dependencies() {
  local kts_files_list="$1"
  "${REPO_ROOT_DIR}/config/bin/sort-dependencies" ${kts_files_list} &> /dev/null
  if [[ $? != 0 ]]; then
    echo -e "${RED}sort-dependencies failed, re-running verbosely. Alternatively, you can run the command locally" >&2
    echo -e "Running format command: './config/bin/sort-dependencies --verbose ${kts_files_list}'${NC}" >&2
    "${REPO_ROOT_DIR}/config/bin/sort-dependencies --verbose" ${kts_files_list} >&2
    exit $?
  fi
}

# Call the sort_dependencies function
if [[ -n ${kts_files_list} ]]; then
  sort_dependencies "${kts_files_list}"
fi

2. Use more descriptive variable names and remove unnecessary variables. This will make the code easier to understand.

# Get a list of staged build.gradle.kts files
kts_files_list="$(git diff --cached --name-only --diff-filter=ACMR "-G.*" | grep -Ei "build\.gradle\.kts$" | grep -v -x -F "tooling/slack-platform/build.gradle.kts")"

# Use basename to extract filenames
partially_staged_filenames=$(echo "$original_partially_staged_chksum" | awk '{print $NF}')

3. Add error handling and logging to provide more information about errors. This will make it easier to troubleshoot issues.

if [[ $? != 0 ]]; then
  echo -e "${RED}sort-dependencies failed, re-running verbosely. Alternatively, you can run the command locally" >&2
  echo -e "Running format command: './config/bin/sort-dependencies --verbose ${kts_files_list}'${NC}" >&2
  "${REPO_ROOT_DIR}/config/bin/sort-dependencies --verbose" ${kts_files_list} >&2
  exit $?
fi

4. Use more modern and concise syntax. For example, use [[ -n ${kts_files_list} ]] instead of [[ ! -z ${kts_files_list} ]].

if [[ -n ${kts_files_list} ]]; then
  sort_dependencies "${kts_files_list}"
fi

5. Consider using a more efficient and readable construct. For example, use basename to extract filenames.

partially_staged_filenames=$(echo "$original_partially_staged_chksum" | awk '{print $NF}')