如何打破 Doxygen 评论中的长 URL 以满足最大行长？答案

【问题标题】：How to break long URLs in Doxygen comments to satisfy maximum line length?如何打破 Doxygen 评论中的长 URL 以满足最大行长？
【发布时间】：2013-06-19 07:31:46
【问题描述】：

编程语言的编码准则限制了行长，例如到 80 个字符。如何向 Doxygen cmets 添加一个长于该限制的 URL？我如何告诉 Doxygen 多行要连接起来形成实际的链接？

例子：

##
# @file  mycode.py
# @sa    See the documentation: http://some.host.some.domain/and_here
#        _we_have_a_very_long_URL_that_can_not_be_written_in_one_line
#        _because_it_would_exceed_the_line_length_limit

上面的例子不起作用，用反斜杠结束行也不起作用（反斜杠只是复制到文档中）。

【问题讨论】：

只是一个想法，没有真正的答案：使用 URL 缩短服务:)
使用 URL 缩短服务是个好主意。不过，如果 Doxygen 能做点什么会很有趣。
URL 缩短服务的缺点是最终链接到源文档中的位置并不清楚，并且对于普通读者而言。

标签： doxygen

【解决方案1】：

你可以这样试试。它对我有用。但是，我不能 100% 确定它会为您工作。我们的 IDE 使用空格作为缩进而不是制表符。因此，当您断开线路，从而断开链接时，它可能无法正常工作。

<a href="http://stackoverflow.com/questions/9098680/
doxygen-link-to-a-url-doesnt-generate-the-link-correctly">
link
</a>

【讨论】：

这会破坏生成的 HTML 文档中的 URL，但它适用于我测试的浏览器。我不确定 LaTeX 和 PDF 等其他输出格式。
是的，你肯定应该做一些测试，我通常只看 HTML 输出，也许 LaTex 和/或 PDF 有一些陷阱
这是我测试时唯一正常工作的选项（包括生成正确链接）。这很可怕，但它有效。我也希望有问题的第三方文档有更短的链接，但无法解决这个问题……

【解决方案2】：

您可以使用别名来缩写长 URL，即

##
# @file  mycode.py
# @sa    See the documentation: @longurl

并在 Doxyfile 中定义

ALIASES = longurl="http://some.host.some.domain/and_here/..."

【讨论】：

我希望在代码中包含 URL。我希望有一个行延续机制（在大多数编程语言的行尾反斜杠）。如果代码被编辑，程序员必须使用别名查找 Doxyfile 来查找 URL。该链接仅在代码文档中有效。

【解决方案3】：

这是执行死灵术一个老问题。我正在回答 C++ 风格的 cmets。但是，如果你让你在表单中链接：

/** 
 * [link_text](http://foo.com/bar/baz/qux/wibble/flob?id=deadbeef123456789abcdefghijklmnopqrstuvwxyz)
 */

您可以通过以下方式包装该 URL，生成的 HTML 输出仍将包含有效的锚标记：

/**
 * [link_
text]
(http://foo.com/bar/baz/qux/wibble/
flob?id=deadbeef123456789abcdefghijklmnopqrstuvwxyz)
 */

显然，这可能会降低注释块的可读性。但这让您了解什么是可能的。这里的主要优点是能够将 URL 放在与链接文本不同的行上，然后能够在 / 之后将其至少换行一次。

【讨论】：

@DonalFellows 您究竟是如何尝试包装链接的，您使用的是什么版本的 doxygen，您是在生成 html 输出还是其他内容？