bash中的＃：（hashtag/pound冒號）的用途

Question

我最近在查看Homebrew源代碼。由於它是一種流行的工具，代碼可能相對乾淨。我注意到他們使用#:評論風格（例如：update.sh）。我在其他任何地方都沒有看到（而且很難搜索符號，所以我找不到任何提及的符號）。這是一個公認的約定嗎？它有特殊的意義嗎？

Answer 1

它看起來是某種聯機幫助頁的某種文檔片段：它以標準聯機幫助頁樣式編寫，並記錄下面的腳本。這是即使在Library/Homebrew/cmd/vendor-install.sh，其中類似的評論，可以發現這是標有@hide_from_man_page更加明顯：

#: @hide_from_man_page 
#: * `vendor-install` [<target>]: 
#:  Install vendor version of Homebrew dependencies. 

因此，據推測，這不是正是如此註釋的所有片段，包括在手冊頁。

但是，您選擇了一個不幸的示例，因爲update被視爲「基本命令」，因此記錄在聯機幫助頁的單獨部分中。讓我們選擇一個非基本的命令，比如style，您可以在Library/Homebrew/cmd/style.rb發現：

#: * `style` [`--fix`] [`--display-cop-names`] [<formulae>|<files>]: 
#: Check formulae or files for conformance to Homebrew style guidelines. 
#: 
#: <formulae> is a list of formula names. 
#: 
#: <files> is a list of file names. 
#: 
#: <formulae> and <files> may not be combined. If both are omitted, style will run 
#: style checks on the whole Homebrew `Library`, including core code and all 
#: formulae. 
#: 
#: If `--fix` is passed and `HOMEBREW_DEVELOPER` is set, style violations 
#: will be automatically fixed using RuboCop's `--auto-correct` feature. 
#: 
#: If `--display-cop-names` is passed, the RuboCop cop name for each violation 
#: is included in the output. 
#: 
#: Exits with a non-zero status if any style violations are found. 

現在，當你看看Library/Homebrew/manpages/brew.1.md.erb，你可以看到，他們是確實這得到手冊頁片段自動包含到主brew.1手冊頁：

# To make changes to this man page: 
# 
# - For changes to a specific command (appears in the `COMMANDS` section): 
# - Edit the top comment in `Library/Homebrew/cmd/<command>.{rb,sh}`. 
# - Make sure to use the line prefix `#:` for the comments to be recognized as 
#  documentation. If in doubt, compare with already documented commands. 
# - For other changes: Edit this file. 
# 
# When done, regenerate the man page and its HTML version by running `brew man`. 

而且here's the line where they get included into the manpage：

<%= commands.join("\n") %> 

你可以看到生成的輸出share/man/man1/brew.1：

.TP 
\fBstyle\fR [\fB\-\-fix\fR] [\fB\-\-display\-cop\-names\fR] [\fIformulae\fR|\fIfiles\fR] 
Check formulae or files for conformance to Homebrew style guidelines\. 
. 
.IP 
\fIformulae\fR is a list of formula names\. 
. 
.IP 
\fIfiles\fR is a list of file names\. 
. 
.IP 
\fIformulae\fR and \fIfiles\fR may not be combined\. If both are omitted, style will run style checks on the whole Homebrew \fBLibrary\fR, including core code and all formulae\. 
. 
.IP 
If \fB\-\-fix\fR is passed and \fBHOMEBREW_DEVELOPER\fR is set, style violations will be automatically fixed using RuboCop\'s \fB\-\-auto\-correct\fR feature\. 
. 
.IP 
If \fB\-\-display\-cop\-names\fR is passed, the RuboCop cop name for each violation is included in the output\. 
. 
.IP 
Exits with a non\-zero status if any style violations are found\. 
. 

和share/doc/homebrew/brew.1.html：

<dt><code>style</code> [<code>--fix</code>] [<code>--display-cop-names</code>] [<var>formulae</var>|<var>files</var>]</dt><dd><p>Check formulae or files for conformance to Homebrew style guidelines.</p> 

<p><var>formulae</var> is a list of formula names.</p> 

<p><var>files</var> is a list of file names.</p> 

<p><var>formulae</var> and <var>files</var> may not be combined. If both are omitted, style will run 
style checks on the whole Homebrew <code>Library</code>, including core code and all 
formulae.</p> 

<p>If <code>--fix</code> is passed and <code>HOMEBREW_DEVELOPER</code> is set, style violations 
will be automatically fixed using RuboCop's <code>--auto-correct</code> feature.</p> 

<p>If <code>--display-cop-names</code> is passed, the RuboCop cop name for each violation 
is included in the output.</p> 

我不知道這是否是shell腳本中可接受的約定，但是在各種語言和/或文檔工具中使用了類似的約定。 JavaDoc（/**），Doxygen（/**,/*!,///,//!），JsDoc（/**）或C9（///）。