web-dev-qa-db-ja.com

シェルスクリプトのパラメーターの文書化

シェルスクリプトのパラメーターを文書化するための規則はありますか？

例えば：

#!/usr/bin/env bash

# <description>
#
# Usage:
#  $ ./myScript param1 [param2]
# * param1: <description>
# * param2: <description>

この特定のテンプレートについて、私が気に入らない点がいくつかあります。

  • スクリプトのファイル名（myScript）はファイル自体に表示されます
  • パラメータの説明がおかしい
  • $の前の先行スペースは視覚的には便利ですが、ブロックコメントで言語が混乱し、一部の検証ツールが混合/一貫性のないインデントについて文句を言う可能性があります（このブロックのスペース、コード用のタブ-タブを好む場合） 、 もちろん）

これに関するガイドラインはありますか？

linuxunixshell
43
AnC

伝統的に、あなたはあなたの引数をusage（）関数に文書化します：

#!/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
41
Chas. Owens

私は通常、使用方法を関数にラップして、-h paramなどから呼び出すことができるようにします。

#!/bin/bash
usage() {
    cat <<EOM
    Usage:
    $(basename $0) Explain options here

EOM
    exit 0
}

[ -z $1 ] && { usage; }
22
Eddy

私はヒアドキュメントを使用してお勧めします：

usage () {
    cat <<HELP_USAGE

    $0  [-a] -f <file>

   -a  All the instances.
   -f  File to write all the log lines
HELP_USAGE
}

の代わりに：

echo "$0  [-a] -f <file>"
echo
echo "-a  All the instances."
echo "-f  File to write all the log lines."

これらすべてのecho行よりもずっとクリーンだと思います。

19
leogtzr

これを行う Vim bash IDE ：

#!/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:  ---
#===============================================================================
12
John Ellinwood

私はむしろ書きたいです：

Usage: `basename $0` [option1]|[option2] param1
  Options:
   - option1:  .....
   - option2:  .....
  Parameters:
   - param1:   .....

標準のUNIXユーティリティ（たとえば、ls --help）のヘルプのフォーマット方法を確認してください

3
Varkhan

スクリプトに使用状況を自動的に出力させることをお勧めします（引数なしで実行しない場合）。

#!/usr/bin/env bash

if [ $# == 0 ]; then
    echo "Usage: $0 param1 [param2]"
    echo "* param1: <description>"
    echo "* param2: <description>"
fi
3
rmmh