通過「超鏈接」獲得文檔的源代碼

Question

我越來越堅持記錄我的所有代碼，向我的團隊中的用戶和其他工程師展示我在哪裏找到給定的信息，或者我在哪裏找到特定的代碼段。

我希望能夠完成的是創建與我的代碼（Verilog/SystemVerilog，VHDL，C/C++和RTL源代碼）的行或文件的鏈接，但真的找到或提出瞭解決方案用任何語言都會對我有益。

這將通過Word文檔來完成，PDF文件，我不介意的設置，使用乳膠等，但我想找到這樣的一種方式。基本上我想點擊一個參考，在那裏我指定了行或文件，並且該文件在編輯器中爲讀者提供。

所有的文件將被放置在所有使用該文件的用戶都可以看到必要文件的位置，而我的首選項是能夠在Linux中執行此操作。

Answer 1

您可以使用Doxygen生成html文檔。我用它來從我的VHDL源代碼中生成html文檔。

如果您想引用外部文檔，doxygen確實支持外部鏈接。我從來沒有試過這樣做，但文檔建議他們自動提取。

http://www.stack.nl/~dimitri/doxygen/manual/autolink.html

一個例子是（截斷並從擴展：http://www.stack.nl/~dimitri/doxygen/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是獨立於語言的，因此可以用於所有建議的代碼類型。儘管要獲得最適合你的輸出，你必須稍微擺弄一下配置文件。