There might be a lot of discussions which build system is the best – I once decided to invest into understanding cmake and never looked back. It’s not perfect, but it’s really easy to set up a build especially a cross-platform one.

There is actually no discussion that one should document his/her source code thoroughly – you should just do it. Over a decade ago I chose to use doxygen and I also didn’t regret it. Also cross-platform and does its job.

It’s actually quite easy to marry both tools since cmake provides doxygen support and here I just present shortly the steps needed to activate doxygen.

First install cmake and doxygen. On Linux this packages will be provided by your distribution, on Mac OS X I would just use homebrew (“brew install cmake doxygen”) and on Windows I actually like chocolatey quite a lot (“choco install doxygen.install” and “choco install cmake”). After installation (and maybe a restart or at least rerunning the CLI) you should make sure that cmake and doxygen are installed (“cmake –version” and “doxygen –version”).

Then add the following lines to you CMakeLists.txt (I added the code after the find_packages() part).

# look for Doxygen package
find_package(Doxygen)

if(DOXYGEN_FOUND)
  # exclude sqlite code
  set(DOXYGEN_EXCLUDE_PATTERNS
        */sqlite3/*
  )

  # doxygen settings can be set here, prefixed with "DOXYGEN_"
  set(DOXYGEN_SOURCE_BROWSER YES)
  set(DOXYGEN_EXTRACT_PRIVATE YES)
  set(DOXYGEN_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/api-docs")

  # this target will only be built if specifically asked to.
  # run "make api-docs" to create the doxygen documentation
  doxygen_add_docs(
    api-docs
    ${PROJECT_SOURCE_DIR}
    COMMENT "Generate API-documents for NoteSearch."
  )
endif(DOXYGEN_FOUND)

This will create a custom target, which is not automatically run with the compilation. Which makes sense for me, since I don’t need the documentation updated all the time. If you want to create the documentation just run “make api-docs” (or similar). If you use Visual C++ there will be a project “api-docs” which you can build on demand.