Keep your code documented

Posted on by Anastasia Kazakova

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

Comments below can no longer be edited.

22 Responses to Keep your code documented

  1. Roman says:

    May 18, 2016

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

  2. Arkady Shapkin says:

    May 19, 2016

    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?

    • Anastasia Kazakova says:

      May 20, 2016

      We plan to generate @throw for functions throwing exception.
      As for the second case – we may consider, thanks for the idea!

    • Zach says:

      June 13, 2016

      Seconded on the Doxygen for overridden methods. INHERIT_DOCS is on by default in Doxygen, so having the same functionality in Clion would be awesome.

  3. Jonathan O'Connor says:

    May 20, 2016

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

    • Anastasia Kazakova says:

      May 20, 2016

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

    • Anastasia Kazakova says:

      May 20, 2016

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

  4. Nikos says:

    May 20, 2016

    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:

    May 26, 2016

    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.

    • Anastasia Kazakova says:

      May 26, 2016

      Thanks for a good idea! We’ll consider it https://youtrack.jetbrains.com/issue/CPP-6835 – upvote and follow to get the updates.

    • Dullin says:

      September 3, 2016

      For the record, using /// generates \brief and /** generates @brief. Seems to be a undocumented feature (or at least I didn’t find where it was said).

      • Anastasia Kazakova says:

        September 3, 2016

        That depends on your settings in Editor | Code Style | C/C++ | Code generation. By default \param is used for line comments and @param for block comments.

  6. Michel says:

    May 27, 2016

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

    • Anastasia Kazakova says:

      May 27, 2016

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

  7. Silvio Clécio says:

    December 21, 2016

    Hello,

    Great feature!

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

    Thank you!

    • Anastasia Kazakova says:

      December 21, 2016

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

  8. Miguel Carvajal says:

    January 17, 2017

    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:

      January 17, 2017

      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:

    January 25, 2017

    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…

    • Anastasia Kazakova says:

      January 25, 2017

      You can switch on/off @brief tag generation in settings: Editor | Code Style | C/C++ | Code Generation tab

Subscribe

Subscribe for updates