#: (hashtag/pound 冒号) 在 bash 中的用途是什么
what is the purpose of #: (hashtag/pound colon) in bash
我最近在看 Homebrew 源代码。由于它是一个流行的工具,代码可能相对干净。我注意到他们使用 #:
评论风格(例如:update.sh)。我在其他任何地方都没有看到过(而且很难搜索符号,所以我找不到任何提及它的地方)。这是公认的惯例吗?有什么特殊含义吗?
它看起来像是联机帮助页的某种文档片段:它以标准联机帮助页样式编写,并记录了后面的脚本。这在 Library/Homebrew/cmd/vendor-install.sh
中更为明显,其中可以找到类似的评论,该评论被标记为 @hide_from_man_page
:
#: @hide_from_man_page
#: * `vendor-install` [<target>]:
#: Install vendor version of Homebrew dependencies.
因此,据推测,所有未如此注释的片段都包含在联机帮助页中。
不过,您选择了一个不幸的示例,因为 update
被认为是 "essential command",因此在联机帮助页的单独部分中进行了记录。让我们选择一个非必要的命令,例如 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 脚本中公认的约定,但类似的约定在多种语言中使用 and/or 文档工具,例如JavaDoc (/**
)、Doxygen (/**
、/*!
、///
、//!
)、JsDoc (/**
) 或 C♯ (///
).
我最近在看 Homebrew 源代码。由于它是一个流行的工具,代码可能相对干净。我注意到他们使用 #:
评论风格(例如:update.sh)。我在其他任何地方都没有看到过(而且很难搜索符号,所以我找不到任何提及它的地方)。这是公认的惯例吗?有什么特殊含义吗?
它看起来像是联机帮助页的某种文档片段:它以标准联机帮助页样式编写,并记录了后面的脚本。这在 Library/Homebrew/cmd/vendor-install.sh
中更为明显,其中可以找到类似的评论,该评论被标记为 @hide_from_man_page
:
#: @hide_from_man_page #: * `vendor-install` [<target>]: #: Install vendor version of Homebrew dependencies.
因此,据推测,所有未如此注释的片段都包含在联机帮助页中。
不过,您选择了一个不幸的示例,因为 update
被认为是 "essential command",因此在联机帮助页的单独部分中进行了记录。让我们选择一个非必要的命令,例如 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 脚本中公认的约定,但类似的约定在多种语言中使用 and/or 文档工具,例如JavaDoc (/**
)、Doxygen (/**
、/*!
、///
、//!
)、JsDoc (/**
) 或 C♯ (///
).