Keep your code documented
Some say developers spend most of their time reading code rather than writing it. Unless you aren’t starting a project completely from scratch, this is most likely true.
Code navigation makes the task of reading the source code easier and quicker. However, sometimes you can skip moving to another file to find out what a class is about or what a function does. You can get some information in-place, to save some time and help yourself stay focused. This is what Quick Documentation does: it’s a pop-up that includes information about the symbol, together with hyperlinks to the related types documentation:
The quick pop-up joins the description of the symbol itself (taken from the code) with the comment section (if any) placed near the symbol. Comments can be plain text, but sometimes they include extra stuff, for example Doxygen comments.
In the C++ world Doxygen is quite a popular tool for documenting the code. Doxygen-style comments can be placed across the source code and used for generating full-fledged documentation in various formats. In case you have a project documented this way, you can easily run Doxygen tool from the built-in terminal in CLion to get the documentation. Besides latest CLion 2016.2 EAP made it possible to get more value out of Doxygen comments inside the IDE itself. Let us show you!
Documentation viewer
When going through the code in CLion there is no need to generate full Doxygen-styled documentation, since starting from the recent CLion 2016.2 EAP you can view the Doxygen-styled docs in the Quick Documentation pop-up:
Doxygen-styled information is included in Quick Documentation pop-up in addition to the type information. Doxygen commands are parsed and aligned in a nice-looking way.
If you’d like to explore the function parameters in detail, you can place the caret either at the parameter itself or alternatively at the @param command in the Doxygen comment and invoke the Quick Documentation pop-up:
If function parameters are documented separately from the function description, CLion will merge all the comments and show you the full function’s signature documentation (just like Doxygen does when generating the output):
Reliable rename
While renaming a function or its parameters, you need to get the Doxygen comments updated as well. Otherwise the documentation will become incorrect and thus useless. In CLion, start refactoring (Shift+F6 to call the Rename) and get the Doxygen comments updated as well as other references:
Doxygen typing assistance
CLion is always there to help you type quicker and save your time for more important tasks. Basic assistance comes from the auto-completion feature, and it works for Doxygen commands too, as well as for function parameters:
Please, note that not all commands are available in the completion. Command that are not supported can be found in our tracker.
Even better, if you need to write a Doxygen comment for a function from scratch, simply generate it! Start with typing “/**” or “/*!” (and “///” or “//!” starting from 162.1024.9 CLion 2016.2 EAP build) and then press Enter. In case your function has parameters, returns a value or throws an exception, you’ll get a stub to fill with the documentation text:
Hopefully we’ve demonstrated that CLion can make it easier to keep your code properly documented. Check out the CLion 2016.2 EAP build and let us know what you think!
Cheers,
The CLion Team
Subscribe to CLion Blog updates
