what is the purpose of #: (hashtag/pound colon) in bash

问题

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?

回答1:

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.

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.

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`.

And here's the line where they get included into the manpage:

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

You can see the generated output in 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\.
.

and 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>

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♯ (///).

来源：https://stackoverflow.com/questions/38978159/what-is-the-purpose-of-hashtag-pound-colon-in-bash

标签

bash

comments

hashtag