docs(libvmaf): doxygen comments on 15 undocumented public C-API entry points (round 2)

[lusoris]

Summary

Round-2 follow-on to PR #302 (which closed five targeted gap-findings in
libvmaf.h / picture.h / dnn.h). This pass covers the public surfaces
that PR #302 left untouched, focusing on the headers the ffmpeg patch
stack, the upcoming Go/Rust bindings, and the embedded MCP server consume.

• feature.h (file was 100 % undocumented):
  VmafFeatureDictionary (struct + ownership-transfer rules),
  vmaf_feature_dictionary_set, vmaf_feature_dictionary_free.
• model.h: VmafModelFlags (enum + per-flag semantics),
  VmafModelConfig (struct + per-field), vmaf_model_load,
  vmaf_model_load_from_path, vmaf_model_feature_overload (incl.
  opts_dict ownership transfer), vmaf_model_destroy (incl.
  do-not-destroy-after-collection-handoff), VmafModelCollection,
  VmafModelCollectionScoreType, VmafModelCollectionScore,
  vmaf_model_collection_load, vmaf_model_collection_load_from_path,
  vmaf_model_collection_feature_overload, vmaf_model_collection_destroy.
• dnn.h: vmaf_dnn_session_close (pair-with-open contract).

Each block documents the negative-errno return convention, NULL-safety,
ownership-transfer semantics, and the destroy-pairing required to avoid
double-free of collection-owned sub-models. No semantic / no ABI
change.

Cleanup pass (CLAUDE.md §12 r12 — touched-file lint-clean rule)

The three Netflix-copyright include guards (__VMAF_FEATURE_H__ /
__VMAF_MODEL_H__ / __VMAF_DNN_H__) trip clang-tidy's
bugprone-reserved-identifier check. Renaming them would diverge from
Netflix/vmaf master and break port-only upstream sync (CLAUDE.md §10), so
each #ifndef / #define gets an inline NOLINT citing the
upstream-mirror invariant. This is the exact pattern ADR-0278 endorses for
load-bearing upstream-parity identifiers.

Reproducer / smoke test

meson setup build-cpu-doc core -Denable_cuda=false -Denable_sycl=false
ninja -C build-cpu-doc                  # 726 targets, clean
clang-tidy -p build-cpu-doc \
  core/include/libvmaf/feature.h \
  core/include/libvmaf/model.h \
  core/include/libvmaf/dnn.h            # 0 fork-local warnings
pre-commit run --files \
  core/include/libvmaf/feature.h \
  core/include/libvmaf/model.h \
  core/include/libvmaf/dnn.h \
  changelog.d/added/libvmaf-public-header-doc-comments-round2.md \
  docs/rebase-notes.md                  # green

Inspect the new comments:

grep -n "@brief\|@param\|@return\|@since" core/include/libvmaf/feature.h
grep -n "@brief\|@param\|@return\|@since" core/include/libvmaf/model.h
grep -n "@brief\|@param" core/include/libvmaf/dnn.h | head -20

ADR-0108 deliverables checklist

• Research digest — no digest needed: trivial doc-only addition
  over Netflix-stable signatures already covered by the existing reference
  manual; the ownership-transfer text matches core/src/model.c and
  core/src/dict.c verbatim.
• Decision matrix — no alternatives needed: only-one-way fix;
  every entry point has a single correct description, verified against the
  implementation.
• AGENTS.md invariant note — no rebase-sensitive invariants: doc
  text sits above unchanged upstream signatures and future Netflix merges
  produce tractable 3-way merges. The NOLINT cites name the one invariant
  they preserve (upstream-mirror include guards) and docs/rebase-notes.md
  records that the cites can be retired if upstream ever renames the guards.
• Reproducer / smoke test — see section above.
• Changelog fragment — changelog.d/added/libvmaf-public-header-doc-comments-round2.md.
• Rebase notes — docs/rebase-notes.md — dedicated section
  libvmaf-public-header-doc-gaps-round2 (2026-05-30).

Test plan

• meson setup build-cpu-doc core -Denable_cuda=false -Denable_sycl=false succeeds.
• ninja -C build-cpu-doc succeeds for the 35 targets the touched headers
  pull through (full clean build covers 726 targets — see Reproducer).
• clang-tidy against the 3 touched headers reports 0 fork-local
  warnings (3 reserved-identifier warnings present on master are now
  NOLINT-cited; remaining warnings are in system headers and suppressed).
• pre-commit run --files <all 5 touched files> is green.
• CI: required-checks aggregator green on PR.

Coordination with PR #302

PR #302 is OPEN (draft) and covers libvmaf.h (3 gap-findings) +
picture.h (struct + 8 fields) + dnn.h (vmaf_dnn_session_attached_ep
EP-list dedup). This PR does not overlap with #302:

• feature.h: touched only by this PR.
• model.h: touched only by this PR.
• dnn.h: this PR adds a doxygen block above vmaf_dnn_session_close
  (untouched by docs(libvmaf): close 5 documentation gaps in public headers #302) and adds NOLINT cites on the include guard
  (untouched by docs(libvmaf): close 5 documentation gaps in public headers #302). The two edits are independent and merge cleanly.

If #302 lands first, this branch needs no rebase (no shared lines). If
this PR lands first, #302 will not see any conflict either.

🤖 Generated with Claude Code

[lusoris]

Closing as part of marathon cleanup 2026-05-31 (150 PRs merged today). Content likely superseded by sibling merges. Reopen if specific finding still needs work; bigger PRs preferred going forward per session feedback.

[lusoris]

Superseded by #529 — bundled per 2026-06-01 triage.