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:
quick_doc

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:
doc_doxygen_view

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:
param_view

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):
merge_doxygen

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_rename

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:
doxygen_completion

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:
doxygen_generation

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

This entry was posted in Tips'n'Tricks and tagged , , . Bookmark the permalink.

22 Responses to Keep your code documented

  1. Roman says:

    Doxygen generation is a very helpful feature, missed it a lot when switched from C# to C++.

  2. Arkady Shapkin says:

    Nice! I want this in Resharper C++ :)

    Will it add automatically @throw by function body (or maybe and by called functions doxygen)?
    Will it show doxygen for overridden method without doxygen description but with base class with doxygen?

  3. Jonathan O'Connor says:

    Interesting. I write a lot of YARD formatted comments in my Ruby code. You should implement /*! in RubyMine also. Great idea.

    • Anastasia Kazakova says:

      Feel free to submit to the RubyMine tracker, the team will consider the idea.

    • Anastasia Kazakova says:

      By the way, RubyMine has an intention action that provides the same functionality, I mean generates the comment’s stub.

  4. Nikos says:

    Is it possible to indlude Mathjax? Many of my comments are math heavy, and it would be super helpful, to just write them in Latex and preview in the documentation window.

  5. Aleksey Vitebskiy says:

    Is there a plan to make generated Doxygen comments configurable? Right now the comments are generated Java-style with @ prefixes. We use \ to prefix Doxygen statements.

  6. Michel says:

    How do we bring the documentation pop-up? It does not appear on its own on my code.

    • Anastasia Kazakova says:

      You need to call the quick documentation popup. Ctrl+Q (Lin/Win), F1 (OS X) in the default keymap.

  7. Hello,

    Great feature!

    A have a question: how to generate the documentation (as HTML/PDF)?

    Thank you!

    • Anastasia Kazakova says:

      There is no built-in tool in CLion, however you can call Doxygen command from terminal to generate documentation.

  8. Miguel Carvajal says:

    Do you support Markdown in doxygen as documented [here](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_autolink)
    I an implementing some numerical algorithms in my code and would like to be able to include links to the relevant information about the algorithm

    • Anastasia Kazakova says:

      No, unfortunately, it’s not supported, at least in the Quick Documentation pop-up preview. However, this doesn’t prevent you from still using such links in the Doxygen comments.

  9. Alex says:

    Is there a way to update the template for doxygen comments generated? I’d like to include the @brief tag with a description of the function…

Leave a Reply to Alex Cancel reply

Your email address will not be published. Required fields are marked *