Vscode Doxygen Plugin
Brian Scarano
What I want is to automatically generate doxygen style comments to describe classes, functions and such. The preferred way is to automatically generate the snippet when I type /// or /** in insert mode and it should be context sensitive (as in automatically get the parameter names), like visual studio does for C#.
Integrate with the language server so that rename causes the doxygen references to that same identifier to also be renamed. For example renaming a parameter should automatically also rename the doxygen comment parameter name.
I also found this 9 years old question on SO. But I'd really rather just install some plugins and configure it rather than spending another day writing snippets that I don't know the syntax of. On top of that they will also not update the comments, parameter names, etc.
None of those things provide some sort of integration with the clang language server, where I would get those comments shown as I type for example a function call or get the function name completion in coc. They would also not be renamed if I used the rename refactoring offered by coc through clang.
All of those features are available in many gui applications like visual studio, code lite and even the ancient and discontinued code blocks editor. Sublime Text has the DoxyDoxygen plugin. How do I get that in nvim?
Shameless plug. In lh-cpp/(gotoimpl_with_libclang branch) I have an updated version of my old :DOX command that generates Doxygen comments. Unlike what you're looking for, it's not interactive (e.g. comments won't be updated if you add another parameter).
Regarding LSP, indeed there is no integration as... the Language Server Protocol offers nothing related to code analysis or the generation of comments (last time I've checked). Hence the need to introduce yet-another-dependency in order to analyze function signatures.
In addition to the features of the original stan-vscode (syntax highlighting, code folding, snippets) this also features the ability to automatically format .stan files and will give you feedback in the form of the classic red/yellow squiggles to let you know about compiler errors and warnings in your code.
I see that for the core C++ stan math library the documentation is written with doxygen and documentation for individual functions is available. Can this be leveraged? I know that this is documetnation for the C++ usage, but the function names match, right, so maybe the necessary things could be extracted?
Another idea is to generate a dictionary with function names and the links that are constructed for the function_index on the website: docs/gen_index.py at master stan-dev/docs GitHub so on hover you could get a link to the relevant documentation section
This is the last change I am currently planning on making for now unless the documentation changes @Ven_Popov suggested come to pass, in which case I will overhaul the hovering again. There are a few internal changes in stanc that would improve some things I might look into soon.
I have just published version 0.9.0 of the extension.
This uses the hot-off-the-presses support for #include statements in stanc.js to support formatting and linting of files that contain #includes of other files in the same folder or VSCode workspace.
It also contains some fixes for how #includes are highlighted.
The problem starts with the fact, that rarely the implementation matches the initial design. It even gets worse after a few maintenance cycles: it is very hard to keep the documentation in sync with the actual implementation and project sources. And the user documentation will be easily out of sync too :-(.
Doxygen is a compiler which generates documentation out of source files. Graphviz is a package to draw diagrams and graphs. Mscgen is similar to Graphviz, but simpler and optimized for message sequence diagrams. And Eclox is an Eclipse plugin which integrates everything into Eclipse.
Doxygen is able to generate documentation from standard sources. But there are multiple ways of using special commenting styles to extend the information created. The Doxygen documentation lists different commenting styles.
Graphviz is open source software to create graphs using the dot language. Dot code can be used with Doxygen. With the dot language I define nodes and edges, and the tool will place them automatically. For example I can define a graph with following dot code (example from the dot guide):
All of above can be used without any IDE. But it is a lot of more fun within the Eclipse framework. And here is where Eclox comes into play: Eclox is a plugin which integrates Doxygen (and all above tools) into Eclipse and makes it really easy to use:
It is possible to document things outside the source files. There are many different commands, \mainpage the most important one: it defines the main entry point of the documentation. Using \page and \section is is possible to organize the documentation, and \ref is used to reference labels:
Thanks for explaining this. My work many times is taking a project that people are having problems with and solving those problems. This is a quick and easy way to get the high level overview of what is going on without reading every single C file.
Is there a way to integrate the generated HTML documentation into Eclipse when I press F1? I have to code a library containing doxygen documentation and I want other developers to access that documentation as easyly as possible.
I think this is already noted? You cannot directly generate PDF files (to my knowledge). I generate either RTF and then convert it to PDF, or use the LaTeX option to generate output for PDF. See as well -documentation-and-presentations-latex/
Hi Biet,
I just had to add Eclox to my new Eclipse Kepler installation, and that worked fine for me (download.gna.org/eclox/update/). Can you verify that you have internet access? Maybe the server was down for a short period. Can you retry it?
Hi Enrich,
Thanks for reply. I am just be able to install it on Codewarrior 10.3 but not on Codewarrior 10.6, getting the same problem that I have before. I am very sure that it is CW 10.6 problem.
Doxygen is really primarily about generating HTML (which works great). PDF is either over .rtf of LaTeX. But LaTeX is really something for advanced users. So you might be better to take the .rtf and then convert the file into a pdf in a separate step.
I also use Juno. At the moment I created the Doxyfile with Doxywizard and copied the Doxywizard into the project. In this way it works. But for a new project i need to create the doxyfile with doxywizard again.
Hi Carlos,
it should have been automatically added to the Windows PATH environment variable by the Graphviz installer. Can you check if it is present in the PATH of your windows? If not, you need to add it manually there.
I hope this helps.
Hi Charles,
yes, that auto-comment only seems to work in some places, and not for every function. I do not have a workaround for this. I think the implementation of the auto-comment only covers the most common cases, and as the Eclox plugin is now unmaintained for several years, I doubt that it will be fixed. It is a shame that nobody has been able to pick up that plugin work :-(.
Maybe it is about heap size (see -eclipse-performance-with-increased-heap-size/) or a windows limitation on the command line length? Can you check in the console if the command line length is over 8192 characters where it fails?
The heap size bar does not reach the maximum. I increased the maximum heap size anyway, but that did not fix the problem. How do I view the command? My console seems to be outputting status messages only, and not commands. Perhaps I need not resolve this, as substantial amounts (all?) of the documentation seems to be generated.
yes, indeed the console only writes the status messages. I thought it writes the command lines too. Not sure if this helps, but I had in the past some problems with different versions of doxygen (compiler), but not sure if this is the case here.
CW 10.4 is very old. Have you tried it in CW 10.7? I would need to check, but as your CodeWarrior version is very old, you might have better luck if you would try an older Eclox version? Or Switch to CW for MCU 10.7?
I should note that I do not use IDEs, mostly GUI text editors like Scite or Geany (I find vim/emacs too difficult unfortunately); so I'm looking for either a standalone command-line tool (or say a Python library that does all the heavy lifting, and allows for a pretty trivial executable script that would function as a command-line tool) -- or a plugin for a GUI text editor (or a relatively simple GUI text editor), that can perform such formatting.
Ideally, I'd like this to be a mode in a text editor, such that: if you're within a multiline C /* ... */ comments, then as you type, lines get broken at required width (80 characters), and new lines within the comment automatically get * appended at start.
So, a GUI text editor functionality like that, which is "live" and "multiline-comment aware", can insert/delete * on start of line, and can handle copy/pasting, backspace, and text in front of the cursor, would be truly awesome. Is there anything out there that can work like this?
On the other hand, there is the "command line" type of interaction, where the command line tool receives text input, and returns formatted text output. In text editors, say Scite, it would then be easy to make a Lua script addon to call this tool with the input being the selected text, and then replace the text selection with the output.
In the Windows/Visual Studio world, there is a paid addon called Atomineer Pro Documentation for Visual Studio (found via What is the best tool or technique to write doxygen code comments - Stack Overflow), which can create a skeleton for a documentation comment from a function signature, upon pressing the keyboard shortcut CTRL+SHIFT+D:
4a15465005