docs: add extradiegetic comments to please `golint`

This should help us maintain our `A+` grade.

README.md

@@ -5,6 +5,7 @@
 [![Build Status](https://img.shields.io/github/workflow/status/MieuxVoter/majority-judgment-library-go/Go?style=for-the-badge)](https://github.com/MieuxVoter/majority-judgment-library-go/actions/workflows/go.yml)
 [![Coverage](https://img.shields.io/codecov/c/github/MieuxVoter/majority-judgment-library-go?style=for-the-badge&token=FEUB64HRNM)](https://app.codecov.io/gh/MieuxVoter/majority-judgment-library-go/)
 [![Code Quality](https://img.shields.io/codefactor/grade/github/MieuxVoter/majority-judgment-library-go?style=for-the-badge)](https://www.codefactor.io/repository/github/mieuxvoter/majority-judgment-library-go)
+[![A+](https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=for-the-badge)](https://goreportcard.com/report/github.com/mieuxvoter/majority-judgment-library-go)
 ![LoC](https://img.shields.io/tokei/lines/github/MieuxVoter/majority-judgment-library-go?style=for-the-badge)
 [![Discord Chat https://discord.gg/rAAQG9S](https://img.shields.io/discord/705322981102190593.svg?style=for-the-badge)](https://discord.gg/rAAQG9S)
 

judgment/analysis.go

@@ -13,6 +13,7 @@ package judgment
 // Not sure about that.  Is it worth the hassle?  May change.  Advice welcome.
 //
 
+// ProposalAnalysis holds some of the data we need to compute the Score of a Proposal, and hence its Rank.
 type ProposalAnalysis struct {
 	TotalSize              uint64 // total amount of judges|judgments across all grades
 	MedianGrade            uint8  // 0 == "worst" grade, goes up to the amount of grades minus one
@@ -29,6 +30,7 @@ type ProposalAnalysis struct {
 	//RebuttalGroupSize  uint64
 }
 
+// Reset the ProposalAnalysis to default values.
 func (analysis *ProposalAnalysis) Reset() {
 	analysis.TotalSize = 0
 	analysis.MedianGrade = 0
@@ -42,8 +44,9 @@ func (analysis *ProposalAnalysis) Reset() {
 	analysis.ContestationGroupSize = 0
 }
 
-// This MUTATES THE ANALYSIS, but leaves the proposalTally intact, unchanged.
+// Run MUTATES THE ANALYSIS, but leaves the proposalTally intact, unchanged.
 // MJ uses the low median by default (favors contestation), but there's a parameter if need be.
+// This method is deemed complex by gocyclo ; there's no way around it.
 func (analysis *ProposalAnalysis) Run(proposalTally *ProposalTally, favorContestation bool) {
 	analysis.Reset()
 	analysis.TotalSize = proposalTally.CountJudgments()

judgment/deliberator.go

@@ -1,5 +1,6 @@
 package judgment
 
+// DeliberatorInterface ought to be implemented by all deliberators ; not overly useful for now, but hey.
 type DeliberatorInterface interface {
 	Deliberate(tally *PollTally) (result *PollResult, err error)
 }

judgment/majorityjudgment.go

@@ -5,10 +5,12 @@ import (
 	"sort"
 )
 
+// MajorityJudgment is one of the deliberators ; it implements DeliberatorInterface.
 type MajorityJudgment struct {
 	favorContestation bool // strategy for evenness of judgments ; defaults to true
 }
 
+// Deliberate is part of the DeliberatorInterface
 func (mj *MajorityJudgment) Deliberate(tally *PollTally) (_ *PollResult, err error) {
 
 	amountOfProposals := len(tally.Proposals)
@@ -86,6 +88,8 @@ func (mj *MajorityJudgment) Deliberate(tally *PollTally) (_ *PollResult, err err
 	return result, nil
 }
 
+// ComputeScore is the heart of our MajorityJudgment Deliberator.
+// Not sure it should be exported, though.
 // See docs/score-calculus-flowchart.png
 func (mj *MajorityJudgment) ComputeScore(tally *ProposalTally, favorContestation bool) (_ string, err error) {
 	score := ""

judgment/result.go

@@ -1,10 +1,12 @@
 package judgment
 
+// PollResult holds the result for each proposal, in the original proposal order, or sorted by Rank.
 type PollResult struct {
 	Proposals       ProposalsResults // matches the order of the input proposals' tallies
 	ProposalsSorted ProposalsResults // same Results, but sorted by Rank this time
 }
 
+// ProposalResult holds the computed Rank for a proposal, as well as analysis data.
 type ProposalResult struct {
 	Index    int    // index of the proposal in the input proposals' tallies.  Useful with ProposalSorted
 	Rank     int    // Rank starts at 1 (best) and goes upwards.  Equal Proposals share the same rank.
@@ -15,6 +17,11 @@ type ProposalResult struct {
 // ProposalsResults implements sort.Interface based on the Score field.
 type ProposalsResults []*ProposalResult
 
-func (a ProposalsResults) Len() int           { return len(a) }
+// Len is part of sort.Interface
+func (a ProposalsResults) Len() int { return len(a) }
+
+// Less is part of sort.Interface
 func (a ProposalsResults) Less(i, j int) bool { return a[i].Score < a[j].Score }
-func (a ProposalsResults) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
+
+// Swap is part of sort.Interface
+func (a ProposalsResults) Swap(i, j int) { a[i], a[j] = a[j], a[i] }

judgment/tally.go

@@ -2,12 +2,13 @@ package judgment
 
 import "fmt"
 
+// PollTally describes the amount of judgments received by each proposal on each grade.
 type PollTally struct {
 	AmountOfJudges uint64           // Helps balancing tallies using default judgments.
 	Proposals      []*ProposalTally // Tallies of each proposal.  Its order is preserved in the result.
 }
 
-// Mutates the PollTally
+// BalanceWithStaticDefault mutates the PollTally
 func (pollTally *PollTally) BalanceWithStaticDefault(defaultGrade uint8) (err error) {
 	for _, proposalTally := range pollTally.Proposals {
 		proposalErr := proposalTally.FillWithStaticDefault(pollTally.AmountOfJudges, defaultGrade)
@@ -18,7 +19,7 @@ func (pollTally *PollTally) BalanceWithStaticDefault(defaultGrade uint8) (err er
 	return nil
 }
 
-// Mutates the PollTally
+// BalanceWithMedianDefault mutates the PollTally
 func (pollTally *PollTally) BalanceWithMedianDefault() (err error) {
 	for _, proposalTally := range pollTally.Proposals {
 		proposalErr := proposalTally.FillWithMedianDefault(pollTally.AmountOfJudges)
@@ -31,16 +32,19 @@ func (pollTally *PollTally) BalanceWithMedianDefault() (err error) {
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
+// ProposalTally holds the amount of judgments received per Grade for a single Proposal
 type ProposalTally struct {
 	Tally []uint64 // Amount of judgments received for each grade, from "worst" grade to "best" grade.
 }
 
+// Analyze a ProposalTally and return its ProposalAnalysis
 func (proposalTally *ProposalTally) Analyze() (_ *ProposalAnalysis) {
 	analysis := &ProposalAnalysis{}
 	analysis.Run(proposalTally, true)
 	return analysis
 }
 
+// Copy a ProposalTally (deeply)
 func (proposalTally *ProposalTally) Copy() (_ *ProposalTally) {
 	// There might exist an elegant one-liner to copy a slice of uint64
 	intTally := make([]uint64, 0, 8)
@@ -52,6 +56,7 @@ func (proposalTally *ProposalTally) Copy() (_ *ProposalTally) {
 	}
 }
 
+// CountJudgments tallies the received judgments by a Proposal
 func (proposalTally *ProposalTally) CountJudgments() (_ uint64) {
 	amountOfJudgments := uint64(0)
 	for _, gradeTally := range proposalTally.Tally {
@@ -60,11 +65,13 @@ func (proposalTally *ProposalTally) CountJudgments() (_ uint64) {
 	return amountOfJudgments
 }
 
+// CountAvailableGrades returns the amount of available grades in the poll (usually 7 or so).
 func (proposalTally *ProposalTally) CountAvailableGrades() (_ uint8) {
 	return uint8(len(proposalTally.Tally))
 }
 
-// Mutates the proposalTally.
+// RegradeJudgments mutates the proposalTally by moving judgments from one grade to another.
+// Useful when computing the score ; perhaps this method should not be exported, though.
 func (proposalTally *ProposalTally) RegradeJudgments(fromGrade uint8, intoGrade uint8) (err error) {
 
 	if fromGrade == intoGrade {
@@ -85,7 +92,7 @@ func (proposalTally *ProposalTally) RegradeJudgments(fromGrade uint8, intoGrade
 	return nil
 }
 
-// Mutates the proposalTally
+// FillWithStaticDefault mutates the proposalTally
 func (proposalTally *ProposalTally) FillWithStaticDefault(upToAmount uint64, defaultGrade uint8) (err error) {
 	// More silent integer casting awkwardness… ; we need to fix this
 	missingAmount := int(upToAmount) - int(proposalTally.CountJudgments())
@@ -104,7 +111,7 @@ func (proposalTally *ProposalTally) FillWithStaticDefault(upToAmount uint64, def
 	return nil
 }
 
-// Mutates the proposalTally
+// FillWithMedianDefault mutates the proposalTally
 func (proposalTally *ProposalTally) FillWithMedianDefault(upToAmount uint64) (err error) {
 	analysis := proposalTally.Analyze()
 	fillErr := proposalTally.FillWithStaticDefault(upToAmount, analysis.MedianGrade)