Skip to content

How to use Hyde

Jump to bottom
Foster Brereton edited this page Oct 19, 2018 · 1 revision

Let's start with a sample C++ file in a libraray we are trying to document. (For the sake of brevity, extraneous comments, #pragmas, etc., have been removed.)

#include <functional>

template <class T>
class point {
public:
    T x;
    T y;

    static constexpr auto zero() { return point(0, 0); }

    constexpr point() noexcept = default;
    constexpr point(T _x, T _y) noexcept : x(std::move(_x)), y(std::move(_y)) {}

    friend inline bool operator==(const point& a, const point& b) {
        return (a.x == b.x) && (a.y == b.y);
    }
    friend inline bool operator!=(const point& a, const point& b) { return !(a == b); }

    friend inline point operator-(const point& a, const point& b) {
        return point(a.x - b.x, a.y - b.y);
    }

    point& operator-=(const point& a) {
        x -= a.x;
        y -= a.y;
        return *this;
    }
};

The Initial Boilerplate

hyde will help us get off the ground by producing boilerplate that we then fill in as a developer. We run the tool in update mode to produce the files we need:

hyde -hyde-yaml-dir=point_api -hyde-update point.hpp --

Let's look at each of the parameters passed to the tool.

  • -hyde-yaml-dir: Specifies the directory where the output will go. If output already exists there, the tool will update it.
  • -hyde-update: Specifies that the documentation should be modified to reflect the current state of the source file.
  • point.hpp: The name of the source file we are documenting
  • --: If there are necessary compiler flags that need to be passed in (predefined macros, include directories, warning flags, etc.) they would come after this token. (If no additional flags are passed, this token is still necessary.)

The above invocation produces the following file structure:

point_api/
  |- point3CT3E/
  |  |- m_zero.md
  |  |- m_operator-3D.md
  |  |- f_operator3D3D.md
  |  |- f_operator-.md
  |  |- index.md
  |  |- m_point3CT3E.md
  |  +- f_operator213D.md
  +- index.md

index.md is a landing page created at every level in the heirarchy specific to that element. The folder point3CT3E (A quasi-URI encoding of point<T>) contains all the related methods and functions (and enumerations, if there were any) of the point<T> class. Files prefixed with m_ denote class methods, while f_ prefixed files denote free functions.

Updating The Documentation

Adding and Removing Routines

Let us say our point class has changed after some period of active development. Specifically, we have removed the operators related to subtraction, and operators related to addition:

#include <functional>

template <class T>
class point {
public:
    T x;
    T y;

    static constexpr auto zero() { return point(0, 0); }

    constexpr point() noexcept = default;
    constexpr point(T _x, T _y) noexcept : x(std::move(_x)), y(std::move(_y)) {}

    friend inline bool operator==(const point& a, const point& b) {
        return (a.x == b.x) && (a.y == b.y);
    }
    friend inline bool operator!=(const point& a, const point& b) { return !(a == b); }

    friend inline point operator+(const point& a, const point& b) {
        return point(a.x + b.x, a.y + b.y);
    }

    point& operator+=(const point& a) {
        x += a.x;
        y += a.y;
        return *this;
    }
};

To update the documentation we invoke hyde the same way as we did before. This time, the pre-existing documentation will be updated by the tool. During the run of hyde, we are given the following output:

./point3CT3E/m_operator-3D.md: extraneous file
./point3CT3E/f_operator-.md: extraneous file

These warnings convey to the user that these files are no longer valid documentation because the routines they represent are no longer present in the sources.

We can also see that two new files, m_operator2B3D.md and f_operator2B.md, were added to the point3CT3E directory.

Validating Documentation

It is possible to use hyde to make sure pre-existing documentation accurately reflects the state of the source(s) you are looking to document. The invocation of the tool is nearly identical as above, only we pass -hyde-validate instead of -hyde-update:

hyde -hyde-yaml-dir=point_api -hyde-validate point.hpp --

The tool's output will have changed a little bit:

./index.md@['owner']: value not documented
# ...
# ...
# ...
./point3CT3E/f_operator2B.md: extraneous file
./point3CT3E/m_operator2B3D.md: extraneous file
Error: YAML documentation failed to validate.

In addition to the output, the tool will return EXIT_FAILURE instead of EXIT_SUCCESS. While the extraneous file error is easily fixed by removing the file(s) listed, the value not documented error requires a little investigation.

Missing v. Optional values

The value not documented error gives us the name of the documentation file (./index.md) as well as the YAML path (owner) where the erroneous value was found. If we look at that file and path, we see the following field:

owner: __MISSING__

Since this file was created from the tool, there are values that require manual developer input. Specifically, the values marked __MISSING__ will not pass validation until they are filled in by the developer. There is another class of values tagged __OPTIONAL__ that are not required for the hyde validator to pass.

Clone this wiki locally