【问题标题】："Standardized" docstring/self-documentation of bash scriptsbash 脚本的“标准化”文档字符串/自文档
【发布时间】：2019-07-23 17:56:54
【问题描述】：

背景

例如，Python 脚本可以通过docstrings 拥有多个“级别”的文档。它的巧妙之处在于，它们可以在每个函数级别、每个方法级别、每个类级别以及最重要的（在我的问题的上下文中）定义：每个文件级别。例如，文件的顶部可能如下所示：

#!/usr/bin/env python
"""
@brief  A script that does cool stuff.
"""

What's especially useful about this feature is that it's easy to extract and print at run-time.

问题

bash 脚本支持这样的功能吗？即是否有一种“标准化”方法来生成文件级文档集（即脚本用途的人类可读描述，usage syntax 等；以便另一个脚本很容易自动解析/提取它信息？我的目标是创建几个自记录的调试脚本，如果已经有标准/事实上的最佳方法来做到这一点，我想避免重新发明轮子。强>

【问题讨论】：

简答：不，bash 本身一无所有。这使得这是一个关于哪些 3rd 方工具可能遵循某种约定的问题，这使得它脱离了主题。

标签： bash python bash shell scripting documentation

【解决方案1】：

Google Shell Style Guide 的“文件头”部分是向 bash 脚本添加“文档字符串”的一种方法。

基本上，答案是使用#，而不是像 Python 那样使用引号。

【讨论】：

【解决方案2】：

bash 的文档字符串没有标准。不过，有手册页（例如https://www.cyberciti.biz/faq/linux-unix-creating-a-manpage/）或信息页（https://unix.stackexchange.com/questions/164443/how-to-create-info-documentation）总是很好。

【讨论】：

太棒了！谢谢你。虽然我更希望能够将文档“嵌入”到脚本中，但这很适合我的用例。

【解决方案3】：

您可以轻松地为 Bash 执行此操作，如果您需要确保与仅 POSIX 的 shell（如 /bin/sh）或主要的 busbox 系统（如 Alpine）兼容，则有点棘手。

Linux 文档项目有一些很好的例子。

http://tldp.org/LDP/abs/html/here-docs.html

这个巧妙技巧的另一个转折点是“自我记录”脚本可能。

示例 19-12。一个自我记录的脚本

#!/bin/bash
# self-document.sh: self-documenting script
# Modification of "colm.sh".

DOC_REQUEST=70

if [ "$1" = "-h"  -o "$1" = "--help" ]     # Request help.
then
  echo; echo "Usage: $0 [directory-name]"; echo
  sed --silent -e '/DOCUMENTATIONXX$/,/^DOCUMENTATIONXX$/p' "$0" |
  sed -e '/DOCUMENTATIONXX$/d'; exit $DOC_REQUEST; fi


: <<DOCUMENTATIONXX
List the statistics of a specified directory in tabular format.
---------------------------------------------------------------
The command-line parameter gives the directory to be listed.
If no directory specified or directory specified cannot be read,
then list the current working directory.

DOCUMENTATIONXX

if [ -z "$1" -o ! -r "$1" ]
then
  directory=.
else
  directory="$1"
fi  

echo "Listing of "$directory":"; echo
(printf "PERMISSIONS LINKS OWNER GROUP SIZE MONTH DAY HH:MM PROG-NAME\n" \
; ls -l "$directory" | sed 1d) | column -t

exit 0

使用 cat 脚本是完成此任务的另一种方法。

DOC_REQUEST=70

if [ "$1" = "-h"  -o "$1" = "--help" ]     # Request help.
then                                       # Use a "cat script" . . .
  cat <<DOCUMENTATIONXX
List the statistics of a specified directory in tabular format.
---------------------------------------------------------------
The command-line parameter gives the directory to be listed.
If no directory specified or directory specified cannot be read,
then list the current working directory.

DOCUMENTATIONXX
exit $DOC_REQUEST
fi

使用函数处理文档和错误消息的更优雅的示例。

#!/bin/sh

usage() {
cat << EOF
Usage: 
  $0 [-u [username]] [-p]
  Options:
    -u <username> : Optionally specify the new username to set password for.  
    -p : Prompt for a new password.
EOF
}

die() {
  echo
  echo "$1, so giving up.  Sorry."
  echo
  exit 2
}

if [ -z "$USER" ] ; then
  die "Could not identify the existing user"
fi

if $PSET ; then
  passwd $USER || die "Busybox didn't like your password"
fi

https://github.com/jyellick/mficli/blob/master/util/changecreds.sh

【讨论】：