在bash中#：(散列表/磅冒号)的目的是什么？

Question

我最近看了一下国产的源代码。因为它是一个流行的工具，所以代码可能比较干净。我注意到他们使用了#:注释样式(例如：update.sh)。我还没有在其他地方见过这种情况(而且很难搜索符号，所以我找不到任何提到它的地方)。这是公认的惯例吗？它有什么特殊的含义吗？

Answer 1

它看起来像是一个手册页的某种文档片段:它是用标准的手册页样式编写的，并记录了下面的脚本。这一点在Library/Homebrew/cmd/vendor-install.sh中更加明显，在这里可以找到一个类似的注释，它被标记为@hide_from_man_page。

#：@hide_from_man_page #：* vendor-install：#：安装主机依赖关系的供应商版本。

因此，可以推测，所有未带注释的片段都包含在手册中。

但是，您选择了一个不幸的例子，因为update被认为是一个“基本命令”，因此被记录在手册的一个单独部分中。让我们选择一个非必要的命令，比如style，您可以在Library/Homebrew/cmd/style.rb中找到它。

#：* style --fix \：#：检查公式或文件是否符合国产风格指南。#：是一个公式名称的列表。#：是一个文件名的列表。#：#：而且可能不会合并。如果两者都被省略，样式将运行#：style检查整个Library，包括核心代码和所有#：公式。#：#：如果--fix被传递并设置了HOMEBREW\_DEVELOPER，那么使用RuboCop的--auto-correct特性将自动修复#：样式违规。#：#：如果传递--display-cop-names，则输出中包含每个违规行为的RuboCop cop名称。#：如果发现任何违反样式的情况，则退出状态为非零。

现在，当您查看Library/Homebrew/manpages/brew.1.md.erb时，可以看到它们确实是自动包含在主brew.1手册中的手册页片段：

若要更改此手册页：##-用于更改特定命令(出现在COMMANDS部分)：#-编辑Library/Homebrew/cmd/<command>.{rb,sh}中的顶部注释。#-确保使用行前缀#:将注释识别为#文档。如果有疑问，请与已经记录在案的命令进行比较。#-对于其他更改:编辑此文件。#完成后，通过运行brew man重新生成手册页及其HTML版本。

和下面是它们被包含在手册中的一行

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

您可以在share/man/man1/brew.1中看到生成的输出。

.TP \fBstyle\fR \fB--修复\fR\fix公式\fR\fIfiles\fR检查公式或文件是否符合国产风格指南。。.IP \fI算式\fR是公式名称的列表。。.IP \fIfiles\fR是一个文件名列表。。不能组合.IP \fR公式\fR和\fIfiles\fR。如果两者都被省略，样式将对整个\fR运行样式检查，包括核心代码和所有公式。。如果传递了.IP \fB--修复\fR，并且设置了\fBHOMEBREW_DEVELOPER\fR，则使用RuboCop\'s \fB--自动更正\fR功能自动修复样式冲突。如果传递.IP If \fB-display- cop - name \fR，则在输出中包含每个违规行为的RuboCop cop名称。如果发现任何样式冲突，.IP退出时状态为非零状态。

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

我不知道这是否是shell脚本中公认的约定，但类似的约定在多种语言和/或文档工具中使用，例如JavaDoc (/**)、DO2 (/**、/*!、///、//!)、JsDoc (/**)或C♯(///)。