hyde
is a utility that facilitates documenting C++. The tool is unique from existing documentation utilities in the following ways:
- Clang based: In order to properly document your C++,
hyde
compiles it using Clang's excellent libTooling library. Therefore, as the C++ language evolves, so too willhyde
. - Out-of-line: Many tools rely on documentation placed inline within source as long-form comments. While these seem appealing at first blush, they suffer from two big drawbacks. First, there is nothing keeping the comments from falling out of sync from the elements they document. Secondly (and ironically), experienced users of these libraries eventually find inline documentation to be more of a distraction than a help, cluttering code with comments they no longer read.
- Jekyll compatible:
hyde
does not produce pretty-printed output. Rather, it produces well structured Markdown files that contain YAML front-matter. These files can then be consumed by other tools (like Jekyll) to customize the structure and layout of the final documentation. - Schema enforcement: Because of the highly structured nature of the output,
hyde
is able to compare pre-existing documentation files against the current state of your C++ sources. Library developers can usehyde
's update mode to facilitate updating documentation against the state of sources. Build engineers can usehyde
's validate mode to make sure changes to a code base are accurately reflected in the latest documentation. In the end, the documentation stays true to the code with minimal effort. - Adaptable: While
hyde
's primary purpose at this point is to output and enforce documentation, the tool can also be used to output AST-based information about your code as a JSON-based IR. This makes room for additional tools to be build atop whathyde
is able to produce, or additional emitters can be added natively to the tool.
hyde
produces intermediate documentation files that the developer then fills in with additional details as necessary. The files are then fed through a static site generation tool (like Jekyll) to produce output like this.
- Homebrew
brew install cmake
brew install llvm
brew install yaml-cpp --with-static-lib
brew install boost
brew install ninja
(optional)
note only tested on ubuntu bionic so far
- Apt
sudo apt-get install libboost-system-dev libboost-filesystem-dev
sudo apt-get install libyaml-cpp-dev
sudo apt-get install libllvm7 llvm-7 llvm-7-dev
sudo apt-get install clang-tools-7 libclang-common-7-dev clang-7 libclang-7-dev
- clone this repo
cd hyde
mkdir build
cd build
cmake .. -GNinja
(or-GXcode
, etc.)ninja
(or whatever your IDE does)
There are several modes under which the tool can run:
-
-hyde-json
- (default) Output an analysis dump of the input file as JSON -
-hyde-validate
- Validate existing YAML documentation -
-hyde-update
- Write updated YAML documentation -
-hyde-src-root = <path>
- The root path to the header file(s) being analyzed. Affectsdefined-in-file
output values by taking out the root path. -
-hyde-yaml-dir = <path>
- Root directory for YAML validation / update. Required for either hyde-validate or hyde-update modes.
This tool parses the passed header using Clang. To pass arguments to the compiler (e.g., include directories), append them after the --
token on the command line. For example:
hyde input_file.hpp -hyde-json -- -x c++ -I/path/to/includes
Alternatively, if you have a compilation database and would like to pass that instead of command-line compiler arguments, you can pass that with -p
.
While compiling the source file, the non-function macro ADOBE_TOOL_HYDE
is defined to the value 1
. This can be useful to explicitly omit code from the documentation.
To output JSON:
./hyde ../test_files/classes.cpp --
To validate pre-existing YAML:
./hyde ../test_files/classes.cpp -hyde-yaml-dir=/path/to/output -hyde-validate
To output updated YAML:
./hyde ../test_files/classes.cpp -hyde-yaml-dir=/path/to/output -hyde-update