docs: update return type annotations in various methods and documentation

julien-boudry · julien-boudry · commit a3f545669705 · 2026-02-24T15:37:44.000+01:00
diff --git a/Docs/api-reference/Election Class/Election--addCandidate().md b/Docs/api-reference/Election Class/Election--addCandidate().md
@@ -1,6 +1,6 @@
 # public Election::addCandidate
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L167)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L169)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--addCandidatesFromJson().md b/Docs/api-reference/Election Class/Election--addCandidatesFromJson().md
@@ -1,6 +1,6 @@
 # public Election::addCandidatesFromJson
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L292)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L294)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--canAddCandidate().md b/Docs/api-reference/Election Class/Election--canAddCandidate().md
@@ -1,6 +1,6 @@
 # public Election::canAddCandidate
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L214)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L216)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--countCandidates().md b/Docs/api-reference/Election Class/Election--countCandidates().md
@@ -1,6 +1,6 @@
 # public Election::countCandidates
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L43)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L45)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--getCandidateObjectFromName().md b/Docs/api-reference/Election Class/Election--getCandidateObjectFromName().md
@@ -1,6 +1,6 @@
 # public Election::getCandidateObjectFromName
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L131)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L133)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--getCandidatesList().md b/Docs/api-reference/Election Class/Election--getCandidatesList().md
@@ -1,6 +1,6 @@
 # public Election::getCandidatesList
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L57)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L59)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--getCandidatesListAsString().md b/Docs/api-reference/Election Class/Election--getCandidatesListAsString().md
@@ -1,6 +1,6 @@
 # public Election::getCandidatesListAsString
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L72)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L74)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--hasCandidate().md b/Docs/api-reference/Election Class/Election--hasCandidate().md
@@ -1,6 +1,6 @@
 # public Election::hasCandidate
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L115)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L117)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--parseCandidates().md b/Docs/api-reference/Election Class/Election--parseCandidates().md
@@ -1,6 +1,6 @@
 # public Election::parseCandidates
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L337)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L339)
 
 ## Description    
 
diff --git a/Docs/api-reference/Election Class/Election--removeCandidates().md b/Docs/api-reference/Election Class/Election--removeCandidates().md
@@ -1,6 +1,6 @@
 # public Election::removeCandidates
 
-> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L240)
+> [Read it at the source](https://github.com/julien-boudry/Condorcet/blob/master/src/ElectionProcess/CandidatesProcess.php#L242)
 
 ## Description    
 
diff --git a/src/Algo/Methods/Smith/SchwartzSet.php b/src/Algo/Methods/Smith/SchwartzSet.php
@@ -61,7 +61,7 @@ public function getResult(): Result
     /**
      * Compute the Schwartz Set.
      *
-     * @return array Array of candidate IDs in the Schwartz Set
+     * @return array<int, int> Array of candidate IDs in the Schwartz Set
      */
     protected function computeSchwartzSet(): array
     {
diff --git a/src/Algo/Methods/Smith/SmithSet.php b/src/Algo/Methods/Smith/SmithSet.php
@@ -62,7 +62,7 @@ public function getResult(): Result
     /**
      * Compute the Smith Set.
      *
-     * @return array Array of candidate IDs in the Smith Set
+     * @return array<int, int> Array of candidate IDs in the Smith Set
      */
     protected function computeSmithSet(): array
     {
diff --git a/src/Algo/Pairwise/Pairwise.php b/src/Algo/Pairwise/Pairwise.php
@@ -160,7 +160,7 @@ public function removeVote(int $key): void
      *
      * @api
      *
-     * @return array Pairwise as an explicit array .
+     * @return array<string,array<string,array<string,int>>> Pairwise as an explicit array .
      *
      * @see Election::getPairwise()
      * @see Election::getResult()
diff --git a/src/Condorcet.php b/src/Condorcet.php
@@ -113,7 +113,7 @@ public static function getVersion(
      * @param $basic Include or not the natural Condorcet base algorithm.
      * @param $withNonDeterministicMethods Include or not non deterministic methods.
      *
-     * @return array Populated by method string name. You can use it on getResult ... and others methods.
+     * @return array<int, string> Populated by method string name. You can use it on getResult ... and others methods.
      */
     public static function getAuthMethods(
         bool $basic = false,
diff --git a/src/Election.php b/src/Election.php
@@ -414,7 +414,7 @@ public function addConstraint(
      *
      * @api
      *
-     * @return array Array with class name of each active constraint. Empty array if there is not.
+     * @return array<int, string> Array with class name of each active constraint. Empty array if there is not.
      *
      * @book \CondorcetPHP\Condorcet\Dev\CondorcetDocumentationGenerator\BookLibrary::VotesConstraints
      *
diff --git a/src/ElectionProcess/CandidatesProcess.php b/src/ElectionProcess/CandidatesProcess.php
@@ -24,7 +24,9 @@ trait CandidatesProcess
     /////////// CONSTRUCTOR ///////////
 
     // Data and global options
+    /** @var array<int, Candidate>  */
     public protected(set) array $candidates = []; // Candidate list
+
     public protected(set) string $nextAutomaticCandidateName = 'A';
 
 
@@ -50,7 +52,7 @@ public function countCandidates(): int
      *
      * @api
      *
-     * @return array List of candidates in an array.
+     * @return array<int, Candidate> List of candidates in an array.
      *
      * @see \CondorcetPHP\Condorcet\Election::countCandidates()
      */
@@ -65,7 +67,7 @@ public function getCandidatesList(): array
      *
      * @api
      *
-     * @return array List of candidates in an array populated with strings instead of Candidate objects.
+     * @return array<int, string> List of candidates in an array populated with strings instead of Candidate objects.
      *
      * @see \CondorcetPHP\Condorcet\Election::countCandidates()
      */
@@ -235,7 +237,7 @@ public function canAddCandidate(
      * @throws CandidateDoesNotExistException
      * @throws VotingHasStartedException
      *
-     * @return array List of removed candidate objects.
+     * @return array<int, Candidate> List of removed candidate objects.
      */
     public function removeCandidates(
         array|Candidate|string $candidates_input
@@ -287,7 +289,7 @@ public function removeCandidates(
      *
      * @throws CandidateExistsException
      *
-     * @return array List of newly registered candidate objects.
+     * @return array<int, Candidate> List of newly registered candidate objects.
      */
     public function addCandidatesFromJson(
         string $input
@@ -332,7 +334,7 @@ public function addCandidatesFromJson(
      * @throws CandidateExistsException
      * @throws VoteMaxNumberReachedException
      *
-     * @return array List of newly registered candidate objects. Count to check if all candidates were correctly registered.
+     * @return array<int, Candidate> List of newly registered candidate objects. Count to check if all candidates were correctly registered.
      */
     public function parseCandidates(
         string $input,
diff --git a/src/ElectionProcess/ResultsProcess.php b/src/ElectionProcess/ResultsProcess.php
@@ -267,7 +267,7 @@ public function getFilteredPairwiseByTags(
      *
      * @api
      *
-     * @return array Pairwise as an explicit array .
+     * @return array<string,array<string,array<string,int>>> Pairwise as an explicit array .
      *
      * @see \CondorcetPHP\Condorcet\Election::getPairwise()
      * @see \CondorcetPHP\Condorcet\Election::getResult()
@@ -287,7 +287,7 @@ public function getExplicitPairwise(): array
      * @param $tags Tags as string separated by commas or array.
      * @param $with Minimum number of specified tags that votes must include, or 0 for only votes without any specified tags.
      *
-     * @return array Return a Pairwise filtered by tags
+     * @return  array<string,array<string,array<string,int>>> Return a Pairwise filtered by tags
      */
     public function getExplicitFilteredPairwiseByTags(
         array|string $tags,
diff --git a/src/ElectionProcess/VotesProcess.php b/src/ElectionProcess/VotesProcess.php
@@ -141,7 +141,7 @@ public function sumValidVoteWeightsWithConstraints(
      * @param $tags Tags list as a string separated by commas or array.
      * @param $with Get votes with these tags or without.
      *
-     * @return array Populated by each Vote object.
+     * @return array<int, Vote> Populated by each Vote object.
      */
     public function getVotesList(
         array|string|null $tags = null,
@@ -324,7 +324,7 @@ public function convertRankingCandidates(array &$ranking): bool
             foreach ($choice as &$candidate) {
                 if (!$this->hasCandidate($candidate, true)) {
                     if ($candidate->provisionalState && $this->hasCandidate(candidate: $candidate, strictMode: false)) {
-                        $candidate = $this->candidates[$this->getCandidateKey((string) $candidate)];
+                        $candidate = $this->candidates[$this->getCandidateKey((string) $candidate)]; // @phpstan-ignore offsetAccess.notFound
                         $change = true;
                     }
                 }
@@ -420,7 +420,7 @@ public function removeVote(
      * @param $tags Tags as string separated by commas or array.
      * @param $with Votes with these tags or without.
      *
-     * @return array List of removed CondorcetPHP\Condorcet\Vote object.
+     * @return array<int, Vote> List of removed CondorcetPHP\Condorcet\Vote object.
      */
     public function removeVotesByTags(
         array|string $tags,
diff --git a/src/Result.php b/src/Result.php
@@ -363,7 +363,7 @@ public function addWarning(int $type, ?string $msg = null): true
      *
      * @param $type Filter on a specific warning type code.
      *
-     * @return array Warnings provided by the by the method that generated the warning. Empty array if there is not.
+     * @return array<int, string> Warnings provided by the by the method that generated the warning. Empty array if there is not.
      */
     public function getWarning(
         ?int $type = null
diff --git a/src/Tools/Randomizers/ArrayRandomizer.php b/src/Tools/Randomizers/ArrayRandomizer.php
@@ -96,7 +96,7 @@ public function countCandidates(): int
      *
      * @api
      *
-     * @return array Return the new vote.
+     * @return array<int, mixed> Return the new vote.
      */
     public function shuffle(): array
     {
diff --git a/src/Vote.php b/src/Vote.php
@@ -129,7 +129,7 @@ public function valid(): bool
      *
      * @api
      *
-     * @return array List of registered tag.
+     * @return array<int, string> List of registered tag.
      *
      * @see Vote::getTagsAsString()
      * @see Vote::addTags()
@@ -269,7 +269,7 @@ public function __toString(): string
      * @param $context An election already linked to the Vote.
      * @param $sortCandidatesInRank Sort Candidate in a Rank by name. Useful for performant internal calls from methods.
      *
-     * @return array Multidimenssionnal array populated by Candidate object.
+     * @return array<int, array<int, Candidate>> Multidimenssionnal array populated by Candidate object.
      */
     public function getRanking(
         ?Election $context = null,
@@ -324,7 +324,7 @@ public function countRanks(): int
      *
      * @param $context An election already linked to the Vote.
      *
-     * @return array Candidates list.
+     * @return array<int, Candidate> Candidates list.
      */
     public function getAllCandidates(
         ?Election $context = null
@@ -454,7 +454,7 @@ protected function computeContextualRankingWithoutImplicit(array $ranking, Elect
      *
      * @param $context An election already linked to the Vote.
      *
-     * @return array Contextual full ranking, with string instead Candidate object.
+     * @return array<int, string> Contextual full ranking, with string instead Candidate object.
      */
     public function getRankingAsArrayString(
         ?Election $context = null
@@ -700,7 +700,7 @@ public function addTags(
      *
      * @param $tags They can be added by string separated by commas or an array.
      *
-     * @return array List of deleted tags.
+     * @return array<int, string> List of deleted tags.
      */
     public function removeTags(
         array|string $tags
