###################################################################
Rust API reference
###################################################################

The full Rust API reference is generated by ``cargo doc --no-deps``
and copied next to this Sphinx site under the ``api/`` subdirectory
of ``htmldoc/``. It covers every public item of the crate (types,
functions, traits, modules) with doc-comment prose, example code
blocks from the crate's tests, and automatic cross-linking between
types.

.. only:: mode_all

   Both crates are included in this build:

   * `quantica (post-quantum) <api/quantica/index.html>`_
   * `arcana (classical) <api/arcana/index.html>`_

.. only:: mode_quantica

   * `quantica (post-quantum) — full API <api/quantica/index.html>`_

.. only:: mode_arcana

   * `arcana (classical) — full API <api/arcana/index.html>`_

How the API reference is produced
=================================

The ``gendoc.sh`` script invokes ``cargo doc --no-deps -p <crate>``
for each crate included in the selected build mode, then copies the
Rust-native output tree from ``target/doc/`` into ``htmldoc/api/``.
The ``--no-deps`` flag keeps the tree small: only the crate(s)
actually part of the selected mode are documented; dependencies
(there are none outside ``core`` / ``alloc`` / ``std``, anyway) are
omitted.

Notes for reviewers
===================

* The Rust API tree is fully self-contained static HTML — there are
  no external fetches. It can be archived, mirrored, or browsed
  offline alongside this Sphinx site.
* Secret-handling types (``DecapsulationKey``, ``SigningKey``,
  ``SharedSecret``, …) carry a redacted ``Debug`` impl and a
  zeroize-on-``Drop`` implementation; this is documented on each
  type's rustdoc page.
* Side-channel hardening is not visible in the public API surface.

.. only:: mode_all or mode_quantica

   See the side-channel documentation (``sca/index.html`` in this
   same HTML tree) for the threat model, the per-algorithm
   countermeasures, and the verification methodology (ctgrind +
   dudect).