Formal documentation for every trait

[mroczect]

Summary

Enhance documentation for all traits in libvctrl_handler by adding formal pre- and post-conditions, invariants, and error semantics.

Context

Traits define the contracts that all implementations must follow. Formal documentation helps implementers avoid subtle bugs and enables formal verification in the future.

Tasks

• For each trait (ObjectStore, RefStore, Hasher, Encoder, Decoder, Signer, Verifier, Transport, RevWalk, TreeDiffer, ConfigStore, Index, ReflogStore, PackWriter, PackReader, Remote, Blame):
  • Document pre-conditions: what must be true before calling a method.
  • Document post-conditions: what is guaranteed after the method returns.
  • Document invariants: properties that always hold (e.g., get after put returns the same data).
  • Document error cases and when each VctrlError variant is returned.
• Update the trait doc comments to include this information in a structured way (e.g., using sections # Preconditions, # Postconditions, # Errors).
• Ensure doctests still pass after modifications.

Acceptance Criteria

• All traits have formal documentation sections.
• cargo doc generates clear, structured pages.
• The documentation is reviewed by at least one other contributor (or automated check passes).

Dependencies

• Fase 0 and Fase 1 handler definitions.