docs: improve doc comments

[rootulp]

Spun out of #691 because these improvements are can be reviewed & merged independently

[codecov-commenter]

Codecov Report

Merging #716 (f83a44c) into main (27632dd) will not change coverage.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main     #716   +/-   ##
=======================================
  Coverage   46.22%   46.22%           
=======================================
  Files          33       33           
  Lines        3217     3217           
=======================================
  Hits         1487     1487           
  Misses       1619     1619           
  Partials      111      111           

Impacted Files	Coverage Δ
pkg/prove/proof.go	82.48% <ø> (ø)
pkg/shares/shares.go	100.00% <ø> (ø)
pkg/shares/split_compact_shares.go	84.00% <ø> (ø)
pkg/shares/parse_compact_shares.go	77.77% <100.00%> (ø)
pkg/shares/parse_sparse_shares.go	88.60% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[evan-forbes]

disabled auto merge to allow the chance to respond to optional change, hope that's okay