Existe-t-il une convention pour documenter les paramètres des scripts Shell?
Par exemple:
#!/usr/bin/env bash
# <description>
#
# Usage:
# $ ./myScript param1 [param2]
# * param1: <description>
# * param2: <description>
Quelques choses que je n'aime pas dans ce modèle particulier:
myScript
) apparaît dans le fichier lui-même$
est visuellement utile, mais peut conduire à une confusion dans les langues avec les commentaires de bloc, ce qui provoque certains outils de validation à se plaindre de l'indentation mixte/incohérente (par exemple, les espaces dans ce bloc, les onglets pour le code - à condition que l'un préfère les onglets, bien sûr)Y a-t-il des directives à ce sujet?
Traditionnellement, vous documentez vos arguments dans la fonction use ():
#!/bin/bash
programname=$0
function usage {
echo "usage: $programname [-abch] [-f infile] [-o outfile]"
echo " -a turn on feature a"
echo " -b turn on feature b"
echo " -c turn on feature c"
echo " -h display help"
echo " -f infile specify input file infile"
echo " -o outfile specify output file outfile"
exit 1
}
usage
J'encapsule généralement mon utilisation dans la fonction afin que je puisse l'appeler à partir d'un paramètre -h, etc.
#!/bin/bash
usage() {
cat <<EOM
Usage:
$(basename $0) Explain options here
EOM
exit 0
}
[ -z $1 ] && { usage; }
Je recommanderais d'utiliser un hérédoc:
usage () {
cat <<HELP_USAGE
$0 [-a] -f <file>
-a All the instances.
-f File to write all the log lines
HELP_USAGE
}
au lieu de:
echo "$0 [-a] -f <file>"
echo
echo "-a All the instances."
echo "-f File to write all the log lines."
Je pense que c'est beaucoup plus propre que toutes ces lignes echo.
Vim bash IDE qui fait ceci:
#!/bin/bash
#===============================================================================
#
# FILE: test.sh
#
# USAGE: ./test.sh
#
# DESCRIPTION:
#
# OPTIONS: ---
# REQUIREMENTS: ---
# BUGS: ---
# NOTES: ---
# AUTHOR: Joe Brockmeier, [email protected]
# COMPANY: Dissociated Press
# VERSION: 1.0
# CREATED: 05/25/2007 10:31:01 PM MDT
# REVISION: ---
#===============================================================================
Je préfère écrire:
Usage: `basename $0` [option1]|[option2] param1
Options:
- option1: .....
- option2: .....
Parameters:
- param1: .....
Essayez d'examiner la façon dont l'aide est formatée pour les utilitaires UNIX standard (ls --help, par exemple)
Je recommanderais que votre script imprime automatiquement son utilisation (s'il ne doit pas être exécuté sans arguments):
#!/usr/bin/env bash
if [ $# == 0 ]; then
echo "Usage: $0 param1 [param2]"
echo "* param1: <description>"
echo "* param2: <description>"
fi