我最近在查看Homebrew源代码。由于它是一种流行的工具,代码可能相对干净。我注意到他们使用#:
评论风格(例如:update.sh)。我在其他任何地方都没有看到(而且很难搜索符号,所以我找不到任何提及的符号)。这是一个公认的约定吗?它有特殊的意义吗?bash中的#:(hashtag/pound冒号)的用途
0
A
回答
0
它看起来是某种联机帮助页的某种文档片段:它以标准联机帮助页样式编写,并记录下面的脚本。这是即使在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(///
)。
相关问题
- 1. 冒号的SQL用途
- 2. localhost.:8088 - “点冒号”符号的用途
- 3. 用法: - (冒号破折号)在bash中
- 4. bash - 数组键名中的冒号
- 5. 冒号文件中的冒号
- 6. Windows冒号中的分号?
- 7. 的preg_replace用冒号
- 8. Powershell中的冒号
- 9. Python中@符号的用途?
- 10. 如何从DPL使用的类别名称中冒号冒号?
- 11. SQL中冒号冒号DELETE LIKE
- 12. 这个Python string-slicing语句中两个冒号的用途是什么?
- 13. Bash错误 - 使用双分号冒号的行上的程序错误
- 14. 使用冒号
- 15. 用于解析带有冒号名称中的冒号的XML的PHP库?
- 16. URL中的ASP.NET MVC冒号
- 17. JavaScript语句中的冒号
- 18. Erlang Cowboy中的冒号
- 19. 冒号和makefile中的$
- 20. 冒号提交名称中冒号的错误
- 21. iCalendar(rfc2445)中的TEXT值应该冒号冒号吗?
- 22. 冒号命令参数中冒号的语法错误
- 23. 在querySelectorAll中使用冒号
- 24. 我该如何在Scala中使用#::/hash冒号冒号?
- 25. EBNF冒号和分号的用法?
- 26. 红宝石中的“冒号”符号
- 27. 如何用c中的冒号索引#
- 28. 如何用bash脚本中的冒号查找并替换正斜杠?
- 29. Bash正则表达式匹配冒号分隔的整数
- 30. 使用阵列密钥中的冒号或如何避免冒号