info: clarify APICapability and OptionalCapabilities docs

[eriknordmark]

A controller has no way to discover the APICapability gates from the API
itself. The enum's comment describes it as covering "features in the
EdgeDevConfig", but it has grown to also cover messages EVE-OS sends — a
controller expecting S.M.A.R.T. information in ZHardwareHealth from a device
below API_CAPABILITY_SMART_REPORT would wait for it indefinitely. The comment
now says both.

It also states explicitly that the enum is a monotonic level, to be compared
with >= rather than tested for equality or set membership. EVE-OS reports a
single top value (pkg/pillar/cmd/zedagent/reportinfo.go assigns
API_CAPABILITY_REPORT_TPM_EVENTLOG), so a controller treating it as a flag set
would silently mishandle it. And it contrasts OptionalCapabilities, which is
the opposite: independent booleans varying by build flavor rather than version.

Smaller fixes in the same area:

• OptionalCapabilities.hw_inventory_support was the only field in its message
  without a comment, and it is what tells a controller whether an empty
  HardwareInventory means "found no hardware" or "cannot report".
• The hardware-oriented Capabilities message is now distinguished from the
  other two, since its comment previously read like a description of
  APICapability.
• API_CAPABILITY_DISABLE_VTPM was truncated at "Support for disabling", and
  API_CAPABILITY_VOLUME_SNAPSHOTS_IMMEDIATE duplicated value 5's comment.

Wire-compatible: comments only. No field numbers, names or types change.
make proto produces no rawDesc churn and no Python change — only Go doc
comments, in the second commit.

[rene]

Isn't the same thing? If so, I prefer to have "Volume snapshots supported"

[eriknordmark]

Not quite the same thing — they gate two different SnapshotType values, so a controller does need to tell them apart.

SNAPSHOT_TYPE_APP_UPDATE only snapshots when the app instance is already being restarted or purged for some other reason, so it costs no extra downtime. SNAPSHOT_TYPE_IMMEDIATE makes EVE stop and restart the app on its own purely to take the snapshot (handleModify sets PurgeInprogress with restartReason = "Restart to create immediate snapshot"), and it takes precedence when both are requested.

The history lines up with that: value 5 landed in 43f3a3a (2023-02) when SNAPSHOT_TYPE_APP_UPDATE was the only type; SNAPSHOT_TYPE_IMMEDIATE arrived in 8ebf050 (2025-02-06) and value 13 three weeks later in e841144, "proto: add capability for immediate snapshots". The comment on 13 was copied verbatim from 5. Since the enum is monotonic, a device at level 5..12 supports snapshots on app update but not immediate ones, and two identical comments give no way to see that.

That said, your point about the wording stands — leading with a raw enum symbol reads worse, and it was asymmetric with value 5. Reworded both lines to keep the familiar phrasing and make the contrast explicit:

API_CAPABILITY_VOLUME_SNAPSHOTS = 5; // Volume snapshots on app instance update supported (SNAPSHOT_TYPE_APP_UPDATE)
...
API_CAPABILITY_VOLUME_SNAPSHOTS_IMMEDIATE = 13; // Volume snapshots on demand supported (SNAPSHOT_TYPE_IMMEDIATE); restarts the app to take one

CAPABILITIES.md rows 5 and 13 updated to match. Let me know if you'd still rather have the bare "Volume snapshots supported" on both.

[rene]

Apart from my comment, LGTM