Best Documentation Tools for C++

Developers and programmers often need to reference their code to help communicate the design and architecture of their applications, or as a quick way to refresh themselves on how it works. Documenting code is essential part of software development

If you are programmer, who works with C++ at least once, you should be well-informed about the documentation tools for C++. This is because these tools will help you a lot in your work and will make your code better described and easier to work with.

Are you curious about best documentation tools for developers? Or about the best tools for code documentation? Do you want to know the most popular source code examples and source code archives? Don’t worry. Here you will find information about different applications, utilities and sources for various programming tasks. There are also some useful software packages which can help you in your work.

One of the most important things about software development is that the code is well-documented. It’s not enough to just have an organized code structure and great programming practices, you need to make sure that people can understand your code and know how to use it effectively. Otherwise, you have a bunch of programmers who have no idea what they’re doing. Which, obviously, is a bad thing. When it comes to documentation, however, there are many different methods available. Here we’ll look at the best documentation tools for developers and the relevant reasons why they matter.

What is Software Documentation?

Software documentation is any written document that explains how a piece of software is built, operates, or used. For more complex software, it typically includes a section on general use as well as sections about each of the software’s various functions and features. Documentation comes in many forms, including user tutorials that demonstrate how to perform tasks, printed manuals or books with step-by-step instructions, or knowledge bases and FAQ pages on a company’s website.

Software documentation varies depending on the complexity of the software and the technical knowledge of the audience. For example, it can walk end-users through the basics of a piece of consumer software, assist IT and system administrators with software installation, and help software developers build or update programs.

Hyde

Hyde is hosted at https://github.com/adobe/hyde. Below is a screenshot of the API reference for the stlab libraries, powered by Hyde:

Hyde is written in C++ itself, and is typically built from source, using CMake, and runs on macOS and Linux. The input to the tool is your C++ API, for example a header file. The output is a structure of markdown files, each with a section of YAML meta-data at the top. A site generator like Jekyll consumes these files and prepares them for serving as static HTML.

Workflow

Unlike other tools, Hyde does not extract inline documentation from your C++ code. Instead, Hyde creates a set of files upon first run, to which developers need to add documentation. As the API changes, Hyde is run again, and updates the existing files, and adds new ones for new classes for example. You can also use the validation mode to verify that the documentation structure is in sync with the C++ API – a good feature for use with continuous integration systems.

Evaluation

So how does Hyde contribute to our objectives?

• Developers edit the generated output, making it quite easy to document every aspect of the C++ API: Markdown files can be edited with many tools, even from GitHub via the web interface.
• Hyde maintains a stable hierarchy of files, which makes it suitable for creating links in markdown.
• You can limit the view on the public API by excluding namespaces and hiding private/protected class members using the --namespace-blacklist=<string> and the --access-filter-public command line options.
• The sub-set of the API reference that’s co-maintained by Hyde is to be combined with the rest of your conceptual documentation written in markdown. The static site generator then turns that into one package of HTML/CSS/etc., for serving on the web.

Standardese

Next in line is Standardese, a tool that aims to be the “nextgen Doxygen”: https://github.com/standardese/standardese. Its output is by default markdown. This is how it looks like when applied to the SixtyFPS C++ Interpreter API documentation:

Standardese is also written in C++. While it is straight-forward to build with CMake, there is also an official Docker image (standardese/standard) that makes it very convenient to run from anywhere. The input is your C++ API as a header file and the output are plain markdown files.

Workflow

Standardese follows the more traditional approach of parsing your C++ code and extracting the documentation from comments within. Inside the comments markdown is expected, no inline HTML is supported.

Evaluation

• The documentation lives right where the API is defined, which means that everything the tool sees can be documented. By default, the generated markdown files represent the input header file structure. There are commands influencing the way entities are grouped together.
• You can write links to other parts of the reference using a markdown link with an empty url: [link-text](<> "unique-name"). If the unique name is fully qualified (such as sixtyfps::interpreter::Component), Standardese will automatically create the link to the correct markdown file and anchor within. What’s particularly neat though is that out of the box it turns links to types and functions within the std:: to a link to https://en.cppreference.com/w/.
• By default only public class members are visible, and the --input.blacklist_namespace command line option allows blending out namespaces.
• The resulting markdown files can be served straight from GitHub pages, for example.

Doxygen + Breathe + Exhale + Sphinx

Last, but not least, we’re going to take a brief look at a popular combination of tools that work together: Doxygen, Sphinx, with the Breathe and Exhale extensions. Doxygen is the the “Volkswagen Beetle” under the C++ documentation tools: It’s been around for many years and it’s very reliable. Sphinx is the documentation generator that’s very popular in the vibrant Python 🐍 community. Combined with two extensions this is what we’re using for SixtyFPS at the moment:

Workflow

The setup for this combination starts at Sphinx. It is driven by a central configuration file (conf.py), comes with many plugins and different themes. The input is reStructuredText. We use the Exhale extension to automatically launch Doxygen, which parses the C++ API and produces a generic XML file structure. These XML files are consumed by the Breathe extension to produce reStructuredText. The sphinx-build command is driving this entire process, and the output is a directory structure of HTML (and CSS, etc.) that is suitable for direct serving on the web.

Doxygen does the heavy lifting of extracting the documentation from comments in the C++ code. It has its own configuration file with many ways of customizing its behavior.

Evaluation

The setup of these tools is fairly complex, many different projects need to play well together. However, so far, it is also the most flexible solution that ticks our boxes:

• The documentation is written in the C++ header files. Doxygen is well established for extracting annotations for all aspects of the API, from namespaces all the way to individual function parameters.
• Doxygen tries to automatically create links when you mention functions, classes or generally other types. Sometimes it needs a little help with a \ref command though.
• By default, private class members are excluded from the documentation. Similar to the other tools, namespaces need to be explicitly excluded, in this case using the EXCLUDE_SYMBOLS directive in the configuration file.
• The output of Sphinx is plain HTML and CSS, so it is again straight-forward to serve on the web. It comes with search built-in. We also use the MyST extension to feed markdown into Sphinx and produce HTML.

BEST END-USER SOFTWARE DOCUMENTATION TOOLS

1. Whatfix

Whatfix is a Digital Adoption Platform that allows you to create step-by-step walkthroughs that act as real-time software documentation by guiding employees through your software. If you already have a knowledge base, you can display your documentation in a self-help widget.

Whatfix is redefining how software documentation is displayed and consumed, with new content embedded directly within your software applications in forms such as interactive guidance, contextual walkthroughs, self-help FAQs, popup notifications and beacons, and more. The platform also allows you to measure the usage and effectiveness of your documentation with user analytics.

2. Bit.ai

Bit.ai is a documentation collaboration platform that allows you to manage all of your documents in one place. It allows you to create notes, documents, and wikis, and you can manage your company’s documentation across teams or departments.

3. ProProfs

ProProfs knowledge base software is a knowledge management tool that lets you create searchable online FAQs and help docs. In addition, you can add videos, audio, images, and infographics to your documentation to make your software documentation more interactive and compelling.

4. Dropbox Paper

Dropbox Paper is an online document workspace that lets you organize and display text, media, and files all in one place. It’s a web-based tool, so it’s accessible as long as you have an internet connection. If you’re already a Dropbox user, you can create and edit documents without leaving Dropbox.

5. Tettra

Tettra is a tool for internal company use. It’s a wiki and knowledge management system that lets teams create content other employees can read and comment on. This tool is specifically built to work with Slack and features integrations with several other tools, including GSuite, Microsoft Teams, GitHub, and Zapier.

Writing good documentation is hard. Tools can’t solve this problem in themselves, but they can ease the pain. This post will show you how to use Sphinx to generate attractive, functional documentation for C++ libraries, supplied with information from Doxygen. We’ll also integrate this process into a CMake build system so that we have a unified workflow.

For an example of a real-world project whose documentation is built like this, see fmtlib.

Why Sphinx?

Doxygen has been around for a couple of decades and is a stable, feature-rich tool for generating documentation. However, it is not without its issues. Docs generated with Doxygen tend to be visually noisy, have a style out of the early nineties, and struggle to clearly represent complex template-based APIs. There are also limitations to its markup. Although they added Markdown support in 2012, Markdown is simply not the best tool for writing technical documentation since it sacrifices extensibility, featureset size, and semantic markup for simplicity.

Sphinx instead uses reStructuredText, which has those important concepts which are missing from Markdown as core ideals. One can add their own “roles” and “directives” to the markup to make domain-specific customizations. There are some great comparisons of reStructuredText and Markdown by Victor Zverovich and Eli Bendersky if you’d like some more information.

The docs generated by Sphinx also look a lot more modern and minimal when compared to Doxygen and it’s much easier to swap in a different theme, customize the amount of information which is displayed, and modify the layout of the pages.

On a more fundamental level, Doxygen’s style of documentation is listing out all the API entities along with their associated comments in a more digestible, searchable manner. It’s essentially paraphrasing the header files, to take a phrase from Robert Ramey^[1]; embedding things like rationale, examples, notes, or swapping out auto-generated output for hand-written is not very well supported. In Sphinx however, the finer-grained control gives you the ability to write documentation which is truly geared towards getting people to learn and understand your library.

If you’re convinced that this is a good avenue to explore, then we can begin by installing dependencies.

Install Dependencies

Doxygen

Sphinx doesn’t have the ability to extract API documentation from C++ headers; this needs to be supplied either by hand or from some external tool. We can use Doxygen to do this job for us. Grab it from the official download page and install it. There are binaries for Windows, Linux (compiled on Ubuntu 16.04), and MacOS, alongside source which you can build yourself.

Sphinx

Pick your preferred way of installing Sphinx from the official instructions. It may be available through your system package manager, or you can get it through pip.

Read the Docs Sphinx Theme

I prefer this theme to the built-in ones, so we can install it through pip:

> pip install sphinx_rtd_theme

Breathe

Breathe is the bridge between Doxygen and Sphinx; taking the output from the former and making it available through some special directives in the latter. You can install it with pip:

> pip install breathe

CMake

Install the latest release of CMake. If you are using Visual Studio 2017 and up, you will already have a version installed and ready to use. See CMake projects in Visual Studio for more details.

Create a CMake Project

All of the code for this post is available on Github, so if you get stuck, have a look there.

If you are using Visual Studio 2017 and up, go to File > New > Project and create a CMake project.

Regardless of which IDE/editor you are using, get your project folder to look something like this:

CatCutifier/CMakeLists.txt

cmake_minimum_required (VERSION 3.8)

project ("CatCutifier")

add_subdirectory ("CatCutifier")

CatCutifier/CatCutifier/CatCutifier.cpp

#include "CatCutifier.h"

void cat::make_cute() {
  // Magic happens
}

CatCutifier/CatCutifier/CatCutifier.h

#pragma once

/**
  A fluffy feline
*/
struct cat {
  /**
    Make this cat look super cute
  */
  void make_cute();
};

CatCutifier/CatCutifier/CMakeLists.txt

add_library (CatCutifier "CatCutifier.cpp" "CatCutifier.h")

target_include_directories(CatCutifier PUBLIC .)

If you now build your project, you should get a CatCutifier library which someone could link against and use.

Developer Software Documentation

Developers use a specific type of documentation created as part of, or in conjunction with, the software development process. These documents can include release notes that describe features and updates, README files in text documents that offer a brief explanation of the software, system documentation that describes requirements for installation, and API documentation explaining how to integrate and work with an API.

Conclusion

Code documentation is an important part of programming. It allows us to differentiate between what a piece of code does and in general provides the ability to see all possible uses of a function. Additionally, documentation offers an excellent opportunity for learning: the more classes and functions there are, the more you’ll be able to educate yourself.

When creating your own open-source project, or when you are collaborating on an existing project, a good set of documentation is necessary for the success of your project. If the documentation doesn’t exist people will simply give up using it and move on to something else.