bash中＃：（标签/磅冒号）的目的是什么 [英] what is the purpose of #: (hashtag/pound colon) in bash
问题描述
我最近正在查看Homebrew源代码。由于它是一种流行的工具，因此代码可能相对干净。我注意到他们使用了＃：注释样式（例如： update.sh ）。我在其他任何地方都没有看到它（而且很难搜索符号，因此找不到任何提及）。那是公认的惯例吗？
I was recently looking at the Homebrew source code. Since it's a popular tool, the code is probably relatively clean. I noticed they use a #: comment style (example: update.sh). I haven't seen that anywhere else (and it's hard to search for symbols, so I can't find any mentions of it). Is that an accepted convention? Does it have a special meaning?
推荐答案
它似乎是联机帮助页的某种文档片段：它以标准格式编写手册页样式并记录随后的脚本。这在 Library / Homebrew / cmd / vendor-install.sh ，在其中可以找到类似的注释，并标记为 @hide_from_man_page ：
It looks to be some sort of documentation fragment for a manpage: it is written in standard manpage style and documents the script that follows. This is even more obvious in Library/Homebrew/cmd/vendor-install.sh, where a similar comment can be found which is tagged with @hide_from_man_page:
#: @hide_from_man_page
#: * `vendor-install` [<target>]:
#: Install vendor version of Homebrew dependencies.
因此，大概所有未被注释的片段都是
So, presumably, all fragments that are not thusly annotated, are included in the manpage.
但是您选择了一个不幸的示例，因为 update 被视为基本命令因此记录在手册的单独部分中。让我们选择一个非必需的命令，例如 style ，您可以在 Library / Homebrew / cmd / style.rb ：
You picked an unfortunate example, though, because update is considered an "essential command" and is thus documented in a separate section of the manpage. Let's pick a non-essential command such as style, which you can find in 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 ，您可以看到它们确实是 手册页片段，这些片段会自动包含在主要的酿造物中。 1 手册页：
Now, when you look into Library/Homebrew/manpages/brew.1.md.erb, you can see that they are indeed manpage fragments which get automatically included into the main brew.1 manpage:
# 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`.
<%= 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（ / ** ）或C♯（ /// ）。
I don't know whether this is an accepted convention in shell scripting, but similar conventions are used across a wide variety of languages and/or documentation tools, e.g. JavaDoc (/**), Doxygen (/**, /*!, ///, //!), JsDoc (/**), or C♯ (///).
这篇关于bash中＃：（标签/磅冒号）的目的是什么的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
