This patch:
1. Performs the required changes to make the build system able to build
an HTML API documentation using Doxygen.
The way it's done is a replica of what does the Babeltrace 2 project,
which you may be familiar with.
`doc/api` is for all API documentation projects while
`doc/api/liblttng-ctl` is the specific liblttng-ctl API documentation
project.
To build and view the HTML API documentation:
a) Configure the project with the `--enable-api-doc` option.
b) Build and install the project.
c) Open
`$prefix/share/doc/lttng-tools/api/liblttng-ctl/html/index.html`,
where `$prefix` is the installation prefix (for example,
`/usr/local`).
2. Fully documents some modules while not documenting others at all.
Because some liblttng-ctl headers contain functions/types which
conceptually belong to more than one module (unlike in Babeltrace 2),
I decided to put all the Doxygen group (module) definitions and any
"extra" module documentation in `dox/groups.dox`. The latter is a
huge file of which most of the contents was copied from the
LTTng-tools manual pages (and from the online LTTng Documentation)
and adapted to the C API context.
Images are direct copies from the LTTng Documentation.
The complete module tree and its state, as of this patch, is as
follows, where ✅ means it's fully documented and ❌ means it's not
documented at all:
✅ Home page
✅ General API (error codes, session daemon connection,
common definitions)
Includes parts of `lttng.h`, `lttng-error.h`, and
`constant.h`.
✅ Recording session API
Includes parts of `lttng.h`, `channel.h`, `handle.h`,
`domain.h`, and `session.h`.
✅ Recording session descriptor API
Includes all `session-descriptor.h`.
✅ Recording session destruction handle API
Includes all `destruction-handle.h`.
✅ Domain and channel API
Includes parts of `channel.h`, `domain.h`, and `event.h`.
✅ Recording event rule API
Includes parts of `event.h`.
❌ Process attribute inclusion set API
Would include parts of `tracker.h`.
✅ Recording session clearing API
Includes all `clear.h` and `clear-handle.h`.
❌ Recording session snapshot API
Would include all `snapshot.h`.
❌ Recording session rotation API
Would include all `rotation.h` and `location.h`.
❌ Recording session saving and loading API
Would include all `save.h` and `load.h`.
✅ Instrumentation point listing API
Includes parts of `event.h`.
❌ Trigger API
Would include all `trigger/trigger.h`.
❌ Trigger condition API
Would include all `condition/buffer-usage.h`,
`condition/condition.h`, `condition/evaluation.h`,
`condition/session-consumed-size.h`, and
`condition/session-rotation.h`.
❌ "Event rule matches" trigger condition API
Would include all `condition/event-rule-matches.h`.
❌ Event rule API
Would include all headers in `event-rule` as well
as all `kernel-probe.h` and `userspace-probe.h`.
❌ Log level rule API
Would include all `log-level-rule.h`.
❌ Event expression API
Would include all `event-expr.h`.
❌ Event field value API
Would include all `event-field-value.h`.
❌ Trigger action API
Would include all `action/action.h`,
`action/firing-policy.h`, `action/list.h`, `action/path.h`,
`action/rate-policy.h`, `action/rotate-session.h`,
`action/snapshot-session.h`, `action/start-session.h`, and
`action/stop-session.h`.
❌ Notify trigger action API
Would include all `action/notify.h`,
`notification/channel.h`, and
`notification/notification.h`, as well as parts of
`endpoint.h`.
❌ Error query API
Would include all `error-query.h`.
I'm voluntarily not documenting the health API (`health.h`), as I
believe it's not super important for most users. We could document it
on demand.
In `groups.dox`, the groups of the undocumented modules are already
defined, so that the complete tree above is visible in the rendered
"API reference" section. The undocumented modules simply show the
text "To be done". Because there are references to undocumented
modules in `groups.dox` and in the documented headers, this means
that the links at least resolve.
Note that there are non-comment changes in `include/lttng`: I needed
to name some anonymous, nested types so that I could reference their
members, as you can only link to the member of a named type with
Doxygen. For example, the type of the `u` union member of
`struct lttng_event_context` is now `union lttng_event_context_u`;
then you can reference its `probe` member as such:
`lttng_event_context::lttng_event_context_u::probe` (_not_
`lttng_event_context::u::probe`).
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: I2783419159f4892a992fe5bc760b6e2cd6d13a60