The full manual can be found here: http://www.doxygen.nl/manual/docblocks.html
In case that would apply here would be the inline comments:
The line
uint32_t aaa; //[0x8001FE04] Base Trap Vector Table Pointer
Would turn into something like:
uint32_t aaa; /**< [0x8001FE04] Base Trap Vector Table pointer */
Search that page for "Putting documentation after members"
I would probably also add the \struct documentation as well.
Take a look at the C++ syntax of Doxygen. http://www.doxygen.nl/manual/docblocks.html
​
The CLion IDE will recognize the start of a Doxygen block.
​
Some IDEs will highlight "todo" or "TODO" in comments and when used with Doxygen's @todo will include a sidebar reference in the IDE.
Doxygen is a great tool for documentation! I see it now has a lot of languages supported, such as C#, C++, Java, and python!
Here is a link to the site for your reference: http://www.doxygen.nl
Hope this helps!
Ah ha... Then what you might be looking for is something like a documentation generator.
I haven't used it myself, but you might want to check out doxygen or something similar.
Good luck -- let us know if it works out.
Fortunately for me, my dad works in the industry so I kinda took what they were using and went with that. So I used DoxygenDoxygen with the javadoc format (hopefully that link works I’m on mobile so I kinda suck at this stuff lol). I write C++ / C# though and Doxygen is rather popular in that area. As far as web development goes I have no idea what is popular, but there are probably thousands of people even in this subreddit who would love to give you tips about what they are using!
Again, I don’t think it really matters which style you pick, so long as you do it to the standard and can show that you know how. It’s insanely easy to get hired and have to learn a new commenting style, new version control software, new workflow system (is that what it’s called?) etc. what companies really want to see is that you have the good habits and can be flexible. If they see you follow -any- commenting standard or anything like that they will know you can easily catch onto their standards because you already have the good habits.
Edit : see, I suck at mobile.. I wrote this comment on my own post first lol
Fortunately for me, my dad works in the industry so I kinda took what they were using and went with that. So I used DoxygenDoxygen with the javadoc format (hopefully that link works I’m on mobile so I kinda suck at this stuff lol). I write C++ / C# though and Doxygen is rather popular in that area. As far as web development goes I have no idea what is popular, but there are probably thousands of people even in this subreddit who would love to give you tips about what they are using!
Again, I don’t think it really matters which style you pick, so long as you do it to the standard and can show that you know how. It’s insanely easy to get hired and have to learn a new commenting style, new version control software, new workflow system (is that what it’s called?) etc. what companies really want to see is that you have the good habits and can be flexible. If they see you follow -any- commenting standard or anything like that they will know you can easily catch onto their standards because you already have the good habits.
The thing you are looking for is a call graph
I've used doxygen to generate call graphs when inspecting code. You'll need doxygen, graphviz and to make a doxygen project/configuration file for the code you want to inspect.
Oh that makes more sense. Well after struggling for a while I found another workaround. This tool (Dyoxygen)[http://www.doxygen.nl/] let me generate html documentation directly from the source code. Appreciate the help though
Entirely agree with all you said, even that the Kaldi docs are actually one of the better examples. What I don't like is that doxygen seems to shoehorn you into that 90's HTML format. That selector menu on the left is really nothing better than just random collection of links, with not discernible structure to it.
When you look at the doxygen doxygen-generated documentation ( http://www.doxygen.nl ), it's a bit hilarious that the best parts about it are when you don't actually use the doxygen tool but rather just write stuff in markdown.
usually you don't want markdown output, as markdown is used to convert to other formats (usually HTML).
No Doxygen cannot output to Markdown; but does support multiple output languages http://www.doxygen.nl/manual/output.html
standardese can output commonmark (which is it's markdown variant of choice) according to the source code; though I've never used it.
My perspective is that ML should have two workflows:
It is heavily dependent on how large an organization and the investment being made in ML: if in a small organization (or on a very small ML-focused team), the Experimental workflow should take priority - better to deliver value with some associated risk than be prevented from delivering anything by overly involved processes. If you're in even a moderately sized enterprise environment, I'd advocate for at least some of the recommendations your new team member is bringing.
On the documentation front, I'd be much more inclined to support a code-based documentation solution (something along the lines of Doxygen or Sphinx, because trying to maintain separate documentation is just asking for trouble (kept separately, your code and documentation will quickly diverge... just the nature of the beast).