源代码通过文件的“超链接”

时间:2013-05-31 22:20:17

标签: hyperlink documentation code-documentation

我越来越坚持记录我的所有代码并向我的团队中的用户和其他工程师演示,我找到了给定的信息,或者我找到了特定的代码段。

我希望能够完成的是创建指向我的代码的行或文件的链接(Verilog / SystemVerilog,VHDL,C / C ++和RTL源),但是真正找到或想出了这样做的解决方案任何语言对我都有好处。

这可以通过Word文档,PDF文件完成,我不介意设置,使用LaTeX等,但我想找到一种方法。基本上我想点击一个引用,在那里我指定了行或文件,然后在阅读器的编辑器中显示该文件。

所有文档都放在使用该文件的所有用户都可以看到必要文件的位置,我的偏好是能够在Linux中执行此操作。

1 个答案:

答案 0 :(得分:1)

您可以使用doxygen生成html文档。我用它来从我的VHDL源代码中生成html文档。

如果您想引用外部文档,doxygen确实支持外部链接。我从未尝试这样做,但文档表明它们会自动提取。

http://www.doxygen.nl/manual/autolink.html

一个例子是(从http://www.doxygen.nl/manual/docblocks.html

采取并扩展
-------------------------------------------------------
--! @file
--! @brief 2:1 Mux using with-select
-------------------------------------------------------

library ieee;
use ieee.std_logic_1164.all;

--! Mux entity brief description

--! Detailed description of this mux
--! Documentation can be found at http://the_documentation.html
entity mux_using_with is
port (
    ...
);
end entity;

运行doxygen后,您将获得一组超链接文档,包括自动化层次结构图,并引用您的外部文档。

我发现层次结构图非常有用,不会打扰任何外部绘制的图片,因为它似乎是一个重复的工作。

编辑: 我应该补充一点,doxygen与语言无关,因此可以在所有建议的代码类型中使用。您需要稍微调整一下配置文件,以获得最适合您的输出。