2020-05-09

5/9

シェルスクリプトのドキュメントコメントをPODで書くのはもうやめていいかな

いつだったか、何かの本でそういう書き方を見てからずっとそうやってる。

例:

#!/usr/bin/env bash

:

exit 0

: <<'__EOF__'

=encoding utf8

=head1 NAME

B<my-script> - short description

=head1 DESCRIPTION

:

=cut

__EOF__

これでPODに食わせるとドキュメントとして解釈してくれるので、スクリプト内では pod2text $0 とかでヘルプを表示できる。

…が、そろそろ pod2text がどの環境にも入っていると想定すべきでないかも…という気がしてきた。
ところが、じゃあどう書いたらいいの？っていうのには決定版がない気がする。

シェルスクリプトにちゃんとコメントを書こうとしている人たちの間では、主に2つの派閥がある気がする:

1. スクリプトのヘッダや関数のヘッダとしてドキュメントコメントをそれなりのフォーマットで書きましょう派。Googleのコーディング規約もこれ
2. usage() 関数内にヒアドキュメントで書きましょう派

いいとこ取りをしてる感じに見えるのは、 usage() 関数でコメントをパースしてヘルプっぽく出力してるもの。
下のような例があった:

• シェルスクリプトでヘルプメッセージをコメントに書いて表示する - Qiita
• 自作シェルスクリプトにヘルプやらバージョンメッセージを実装？する面白い方法があった - Qiita

自分で独自フォーマットのコメントを書いている、という点では、下もこの類型にあたるか:

• シェルスクリプト群のドキュメント書くの面倒だから自動でREADME.mdを生成する - Qiita
• https://github.com/jmcantrell/bashful/blob/master/bin/shdoc

godocみたいなのないかな、と思って「shelldoc」とか「shdoc」とかでぐぐるとたくさん出てくる。

参考:

• シェルスクリプト Tips | UNIX & Linux コマンド・シェルスクリプト リファレンス

Microk8sを使ってみる

※ブログに移した: UbuntuでKubernetesのテスト環境としてMicrok8sをセットアップした - progrhyme’s tech blog