Source Code via "Hyperlink" for Documentation

Question

I'm becoming more insistent on documenting all of my code and demonstrating to users and other Engineers on my team where I am locating given information, or where I found a specific section of code.

What I would like to be able to accomplish is to create links to lines or files of my code (Verilog/SystemVerilog, VHDL, C/C++ and RTL sources) but really finding or coming up with a solution to doing so in any language would be beneficial to me.

This would be done via Word Documents, PDF Files, and I don't mind the setup, using LaTeX, etc., but I would like to find a way of doing so. Essentially I would like to click on a reference, where I specified either the line or the file, and the file is brought up in an editor for the reader.

All documents would be placed where all users using the file can see the necessary files and my preference is to be able to do this in Linux.

Answer 1

You can use doxygen to generate html documentation. I use it to generate html documentation from within the source of my VHDL.

If you wanted to reference external documents, doxygen does support external links. I've never tried doing so, but the documentation suggests they are automatically extracted.

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

An example would be (taken and extended from: 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;

Once doxygen is run, you'll get a set of hyperlinked documentation, including automated hierarchy diagrams, with references to you're external documentation.

I find the hierarchy diagrams useful enough to not bother with any externally drawn pictures, as it seems to be a duplication of work.

EDIT: I should add that doxygen is language independent, so can be used in all of your suggested code types. You'll have to fiddle around with the configuration file a bit though to get the output that suits you best.