Document the exceptions thrown by capability methods in scaladoc

[sideeffffect]

Severity: low · Category: docs

Evidence

• Capability methods that internally decode (StateCapability.get, ServiceInvocationCapability.invoke, …) don't mention they may surface JsonDecodeException, and the infra paths don't note the unchecked DaprException.

Problem
The project's error model is intentionally exception-based, so the thrown types are part of the public contract — but they're mostly implicit. The best-practices the project follows mandate documenting public-API behaviour.

Suggested fix
Add a short note once per capability trait header, e.g. "Throws DaprException on sidecar/infra failure; may throw JsonDecodeException if the stored/returned payload doesn't match T."

[sideeffffect]

Confirmed against src/Capabilities.scala: none of the trait headers document the thrown types, though the error model is exception-based. JsonDecodeException (src/Exceptions.scala:18) is what JsonCodec.decodeOrThrow raises on a payload/T mismatch, and DaprException is the unchecked infra failure.

A one-line @throws-style note per trait header keeps it discoverable in Scaladoc without touching every method. Suggested wording, added to each trait doc comment:

For traits with decode-bearing methods (StateCapability:10, ServiceInvocationCapability:182, BindingsCapability:322, PubSubCapability:139, ActorCapability:410, WorkflowCapability:451, JobsCapability:600, ConversationCapability:673):

  * Throws `DaprException` on sidecar/infra failure; methods that decode a
  * returned/stored payload may throw `JsonDecodeException` if it doesn't match `T`.

For the non-decoding traits (SecretsCapability:231, ConfigurationCapability:271, DistributedLockCapability:375, CryptoCapability:545 — these return String/bytes, no JsonCodec):

  * Throws `DaprException` on sidecar/infra failure.

Note StateCapability.saveWithETag/deleteWithETag already surface ETagMismatchException via the return type (Option[ETagMismatchException]), so the per-trait note plus existing return types cover the full contract. Putting it once per trait (rather than per method) matches the "document public-API behaviour" goal while staying low-maintenance.