Add Documentation Attributes #2

lib/Algo/Pairwise.php

@@ -112,6 +112,9 @@ public function removeVote (int $key) : void
     }
 
     #[PublicAPI]
+    #[Description("Return the Pairwise.")]
+    #[FunctionReturn("Pairwise as an explicit array .")]
+    #[Related("Election::getPairwise", "Election::getResult")]
     public function getExplicitPairwise () : array
     {
         $explicit_pairwise = [];

lib/Candidate.php

@@ -23,6 +23,9 @@ class Candidate implements \Stringable
         ///
 
     #[PublicAPI]
+    #[Description("Build a candidate.")]
+    #[Examples("Manual - Create Candidates||https://github.com/julien-boudry/Condorcet/wiki/II-%23-A.-Create-an-Election-%23-2.-Create-Candidates")]
+    #[Related("Candidate::setName")]
     public function __construct (string $name)
     {
         $this->setName($name);
@@ -38,6 +41,8 @@ public function __toString () : string
     // SETTERS
 
     #[PublicAPI]
+    #[Description("Change the candidate name.\n*If this will not cause conflicts if the candidate is already participating in elections and would namesake. This situation will throw an exception.*")]
+    #[FunctionReturn("In case of success, return TRUE")]
     public function setName (string $name) : bool
     {
         $name = \trim($name);
@@ -68,30 +73,44 @@ public function setProvisionalState (bool $provisional) : bool
     // GETTERS
 
     #[PublicAPI]
+    #[Description("Get the candidate name.")]
+    #[FunctionReturn("Candidate name.")]
+    #[Related("Candidate::getHistory", "Candidate::setName")]
     public function getName () : string
     {
         return \end($this->_name)['name'];
     }
 
     #[PublicAPI]
+    #[Description("Return an history of each namming change, with timestamp.")]
+    #[FunctionReturn("An explicit multi-dimenssional array.")]
+    #[Related("Candidate::getCreateTimestamp")]
     public function getHistory () : array
     {
         return $this->_name;
     }
 
     #[PublicAPI]
+    #[Description("Get the timestamp corresponding of the creation of this candidate.")]
+    #[FunctionReturn("Timestamp")]
+    #[Related("Candidate::getTimestamp")]
     public function getCreateTimestamp () : float
     {
         return $this->_name[0]['timestamp'];
     }
 
     #[PublicAPI]
+    #[Description("Get the timestamp corresponding of the last namming change.")]
+    #[FunctionReturn("Timestamp")]
+    #[Related("Candidate::getCreateTimestamp")]
     public function getTimestamp () : float
     {
         return \end($this->_name)['timestamp'];
     }
 
     #[PublicAPI]
+    #[Description("When you create yourself the vote object, without use the Election::addVote or other native election method. And if you use string input (or array of string).\nThen, these string input will be converted to into temporary candidate objects, named \"provisional\". because you don't create the candidate yourself. They have a provisonal statut true.\nWhen the vote will be added for the first time to an election, provisional candidate object with a name that matches an election candidate, will be converted into the election candidate. And first ranking will be save into Vote history (Vote::getHistory).\n\nSee VoteTest::testVoteHistory() test for a demonstration. In principle this is transparent from a usage point of view. If you want to avoid any non-strict comparisons, however, you should prefer to create your votes with the Election object, or with Candidate Objects in input. But, you must never getback a candidate marked as provisional in an another election in the same time, it's will not working.")]
+    #[FunctionReturn("True if candidate object is in a provisional state, false else.")]
     public function getProvisionalState () : bool
     {
         return $this->_provisional;

lib/Condorcet.php

@@ -53,6 +53,9 @@ abstract class Condorcet
 
     // Return library version number
     #[PublicAPI]
+    #[Description("Get the library version.")]
+    #[FunctionReturn("Condorcet PHP version.")]
+    #[Related("Election::getObjectVersion")]
     public static function getVersion (bool $major = false) : string
     {
         if ($major === true) :
@@ -65,6 +68,9 @@ public static function getVersion (bool $major = false) : string
 
     // Return an array with auth methods
     #[PublicAPI]
+    #[Description("Get a list of supported algorithm.")]
+    #[FunctionReturn("Populated by method string name. You can use it on getResult ... and others methods.")]
+    #[Related("static Condorcet::isAuthMethod", "static Condorcet::getMethodClass")]
     public static function getAuthMethods (bool $basic = false) : array
     {
         $auth = self::$_authMethods;
@@ -80,13 +86,19 @@ public static function getAuthMethods (bool $basic = false) : array
 
     // Return the Class default method
     #[PublicAPI]
+    #[Description("Return the Condorcet static default method.")]
+    #[FunctionReturn("Method name.")]
+    #[Related("static Condorcet::getAuthMethods", "static Condorcet::setDefaultMethod")]
     public static function getDefaultMethod () : ?string {
         return self::$_defaultMethod;
     }
 
 
     // Check if the method is supported
     #[PublicAPI]
+    #[Description("Return the full class path for a method.")]
+    #[FunctionReturn("Return null is method not exist.")]
+    #[Related("static Condorcet::getAuthMethods")]
     public static function getMethodClass (string $method) : ?string
     {
         $auth = self::$_authMethods;
@@ -111,6 +123,9 @@ public static function getMethodClass (string $method) : ?string
     }
 
     #[PublicAPI]
+    #[Description("Test if a method is in the result set of Condorcet::getAuthMethods.")]
+    #[FunctionReturn("True / False")]
+    #[Related("static Condorcet::getMethodClass", "static Condorcet::getAuthMethods")]
     public static function isAuthMethod (string $method) : bool
     {
         return self::getMethodClass($method) !== null ;
@@ -119,6 +134,9 @@ public static function isAuthMethod (string $method) : bool
 
     // Add algos
     #[PublicAPI]
+    #[Description("If you create your own Condorcet Algo. You will need it !")]
+    #[FunctionReturn("True on Success. False on failure.")]
+    #[Related("static Condorcet::isAuthMethod", "static Condorcet::getMethodClass")]
     public static function addMethod (string $methodClass) : bool
     {
         // Check algos
@@ -160,6 +178,9 @@ protected static function testMethod (string $method) : bool
 
     // Change default method for this class.
     #[PublicAPI]
+    #[Description("Put a new static method by default for the news Condorcet objects.")]
+    #[FunctionReturn("In case of success, return TRUE")]
+    #[Related("static Condorcet::getDefaultMethod")]
     public static function setDefaultMethod (string $method) : bool
     {
         if ( ($method = self::getMethodClass($method)) && $method !== self::CONDORCET_BASIC_CLASS ) :

lib/CondorcetUtil.php

@@ -67,6 +67,8 @@ public static function prepareParse (string $input, bool $isFile) : array
 
     // Simplify Condorcet Var_Dump. Transform object to String.
     #[PublicAPI]
+    #[Description("Provide pretty re-formatting, human compliant, of all Condorcet PHP object or result set.\nCan be use before a var_dump, or just to get more simple data output.")]
+    #[FunctionReturn("New formatted data.")]
     public static function format (mixed $input, bool $convertObject = true) : mixed
     {
         if (\is_object($input)) :

lib/CondorcetVersion.php

@@ -19,6 +19,9 @@ trait CondorcetVersion
     protected string $_objectVersion = Condorcet::VERSION;
 
     #[PublicAPI]
+    #[Description("Get the Condorcet PHP version who built this Election object. Usefull pour serializing Election.")]
+    #[FunctionReturn("Condorcet PHP version.")]
+    #[Related("static Condorcet::getVersion")]
     public function getObjectVersion (bool $major = false) : string
     {
         if ($major === true) :

lib/Election.php

@@ -33,6 +33,9 @@ class Election
 
     // Change max parse iteration
     #[PublicAPI]
+    #[Description("Maximum input for each use of Election::parseCandidate && Election::parseVote. Will throw an exception if exceeded.")]
+    #[FunctionReturn("*(int or null)* The new limit.")]
+    #[Related("static Election::setMaxVoteNumber")]
     public static function setMaxParseIteration (?int $maxParseIterations) : ?int
     {
         self::$_maxParseIteration = $maxParseIterations;
@@ -41,6 +44,9 @@ public static function setMaxParseIteration (?int $maxParseIterations) : ?int
 
     // Change max vote number
     #[PublicAPI]
+    #[Description("Add a limitation on Election::addVote and related methods. You can't add new vote y the number of registered vote is equall ou superior of this limit.")]
+    #[FunctionReturn("*(int or null)* The new limit.")]
+    #[Related("static Election::setMaxParseIteration")]
     public static function setMaxVoteNumber (?int $maxVotesNumber) : ?int
     {
         self::$_maxVoteNumber = $maxVotesNumber;
@@ -64,6 +70,7 @@ public static function setMaxVoteNumber (?int $maxVotesNumber) : ?int
         //////
 
     #[PublicAPI]
+    #[Description("Build a new Election.")]
     public function __construct ()
     {
         $this->_Candidates = [];
@@ -143,21 +150,35 @@ public function __clone () : void
 /////////// TIMER & CHECKSUM ///////////
 
     #[PublicAPI]
+    #[Description("Returns the cumulated computation runtime of this object. Include only computation related methods.")]
+    #[FunctionReturn("(Float) Timer")]
+    #[Examples("Manual - Timber benchmarking||https://github.com/julien-boudry/Condorcet/wiki/III-%23-A.-Avanced-features---Configuration-%23-1.-Timer-Benchmarking")]
+    #[Related("Election::getLastTimer")]
     public function getGlobalTimer () : float {
         return $this->_timer->getGlobalTimer();
     }
 
     #[PublicAPI]
+    #[Description("Return the last computation runtime (typically after a getResult() call.). Include only computation related methods.")]
+    #[FunctionReturn("(Float) Timer")]
+    #[Examples("Manual - Timber benchmarking||https://github.com/julien-boudry/Condorcet/wiki/III-%23-A.-Avanced-features---Configuration-%23-1.-Timer-Benchmarking")]
+    #[Related("Election::getGlobalTimer")]
     public function getLastTimer () : float {
         return $this->_timer->getLastTimer();
     }
 
     #[PublicAPI]
+    #[Description("Get the Timer manager object.")]
+    #[FunctionReturn("An CondorcetPHP\Condorcet\Timer\Manager object using by this election.")]
+    #[Related("Election::getGlobalTimer", "Election::getLastTimer")]
     public function getTimerManager () : Timer_Manager {
         return $this->_timer;
     }
 
     #[PublicAPI]
+    #[Description("SHA-2 256 checksum of following internal data:\n* Candidates\n* Votes list & tags\n* Computed data (pairwise, algorithm cache, stats)\n* Class version (major version like 0.14)\n\nCan be powerfull to check integrity and security of an election. Or working with serialized object.")]
+    #[FunctionReturn("SHA-2 256 bits Hexadecimal")]
+    #[Examples("Manual - Cryptographic Checksum||https://github.com/julien-boudry/Condorcet/wiki/III-%23-A.-Avanced-features---Configuration-%23-2.-Cryptographic-Checksum")]
     public function getChecksum () : string
     {
         self::$_checksumMode = true;
@@ -217,12 +238,18 @@ protected function destroyAllLink () : void
   /////////// IMPLICIT RANKING & VOTE WEIGHT ///////////
 
     #[PublicAPI]
+    #[Description("Returns the corresponding setting as currently set (True by default).\nIf it is True then all votes expressing a partial ranking are understood as implicitly placing all the non-mentioned candidates exequos on a last rank.\nIf it is false, then the candidates not ranked, are not taken into account at all.")]
+    #[FunctionReturn("True / False")]
+    #[Related("Election::setImplicitRanking")]
     public function getImplicitRankingRule () : bool
     {
         return $this->_ImplicitRanking;
     }
 
     #[PublicAPI]
+    #[Description("Set the setting and reset all result data.\nIf it is True then all votes expressing a partial ranking are understood as implicitly placing all the non-mentioned candidates exequos on a last rank.\nIf it is false, then the candidates not ranked, are not taken into account at all.")]
+    #[FunctionReturn("Return True")]
+    #[Related("Election::getImplicitRankingRule")]
     public function setImplicitRanking (bool $rule = true) : bool
     {
         $this->_ImplicitRanking = $rule;
@@ -231,12 +258,18 @@ public function setImplicitRanking (bool $rule = true) : bool
     }
 
     #[PublicAPI]
+    #[Description("Returns the corresponding setting as currently set (False by default).\nIf it is True then votes vote optionally can use weight otherwise (if false) all votes will be evaluated as equal for this election.")]
+    #[FunctionReturn("True / False")]
+    #[Related("Election::allowsVoteWeight")]
     public function isVoteWeightAllowed () : bool
     {
         return $this->_VoteWeightRule;
     }
 
     #[PublicAPI]
+    #[Description("Set the setting and reset all result data.\nThen the weight of votes (if specified) will be taken into account when calculating the results. Otherwise all votes will be considered equal.\nBy default, the voting weight is not activated and all votes are considered equal.")]
+    #[FunctionReturn("Return True")]
+    #[Related("Election::isVoteWeightAllowed")]
     public function allowsVoteWeight (bool $rule = true) : bool
     {
         $this->_VoteWeightRule = $rule;
@@ -248,6 +281,10 @@ public function allowsVoteWeight (bool $rule = true) : bool
     /////////// VOTE CONSTRAINT ///////////
 
     #[PublicAPI]
+    #[Description("Add a constraint rules as a valid class path.")]
+    #[FunctionReturn("True on success. Throw Throwable\CondorcetException code 27/28/29 on error.")]
+    #[Examples("Manual - Vote Constraints||https://github.com/julien-boudry/Condorcet/wiki/II-%23-C.-Result-%23-5.-Vote-Constraints")]
+    #[Related("Election::getConstraints", "Election::clearConstraints", "Election::testIfVoteIsValidUnderElectionConstraints")]
     public function addConstraint (string $constraintClass) : bool
     {
         if ( !\class_exists($constraintClass) ) :
@@ -268,12 +305,20 @@ public function addConstraint (string $constraintClass) : bool
     }
 
     #[PublicAPI]
+    #[Description("Get active constraints list.")]
+    #[FunctionReturn("Array with class name of each active constraint. Empty array if there is not.")]
+    #[Examples("Manual - Vote Constraints||https://github.com/julien-boudry/Condorcet/wiki/II-%23-C.-Result-%23-5.-Vote-Constraints")]
+    #[Related("Election::clearConstraints", "Election::addConstraints", "Election::testIfVoteIsValidUnderElectionConstraints")]
     public function getConstraints () : array
     {
         return $this->_Constraints;
     }
 
     #[PublicAPI]
+    #[Description("Clear all constraints rules and clear previous results.")]
+    #[FunctionReturn("Return True.")]
+    #[Examples("Manual - Vote Constraints||https://github.com/julien-boudry/Condorcet/wiki/II-%23-C.-Result-%23-5.-Vote-Constraints")]
+    #[Related("Election::getConstraints", "Election::addConstraints", "Election::testIfVoteIsValidUnderElectionConstraints")]
     public function clearConstraints () : bool
     {
         $this->_Constraints = [];
@@ -286,6 +331,10 @@ public function clearConstraints () : bool
     }
 
     #[PublicAPI]
+    #[Description("Test if a vote is valid with these election constraints.")]
+    #[FunctionReturn("Return True if vote will pass the constraints rules, else False.")]
+    #[Examples("Manual - Vote Constraints||https://github.com/julien-boudry/Condorcet/wiki/II-%23-C.-Result-%23-5.-Vote-Constraints")]
+    #[Related("Election::getConstraints", "Election::addConstraints", "Election::clearConstraints")]
     public function testIfVoteIsValidUnderElectionConstraints (Vote $vote) : bool
     {
         foreach ($this->_Constraints as $oneConstraint) :
@@ -301,6 +350,10 @@ public function testIfVoteIsValidUnderElectionConstraints (Vote $vote) : bool
 /////////// LARGE ELECTION MODE ///////////
 
     #[PublicAPI]
+    #[Description("Import and enable an external driver to store vote on very large election.")]
+    #[FunctionReturn("True if success. Else throw an Exception.")]
+    #[Examples("[Manual - DataHandler]||https://github.com/julien-boudry/Condorcet/blob/master/examples/specifics_examples/use_large_election_external_database_drivers.php")]
+    #[Related("Election::removeExternalDataHandler")]
     public function setExternalDataHandler (DataHandlerDriverInterface $driver) : bool
     {
         if (!$this->_Votes->isUsingHandler()) :
@@ -312,6 +365,9 @@ public function setExternalDataHandler (DataHandlerDriverInterface $driver) : bo
     }
 
     #[PublicAPI]
+    #[Description("Remove an external driver to store vote on very large election. And import his data into classical memory.")]
+    #[FunctionReturn("True if success. Else throw an Exception.")]
+    #[Related("Election::setExternalDataHandler")]
     public function removeExternalDataHandler () : bool
     {
         if ($this->_Votes->isUsingHandler()) :
@@ -326,13 +382,19 @@ public function removeExternalDataHandler () : bool
 /////////// STATE ///////////
 
     #[PublicAPI]
+    #[Description("Get the election process level.")]
+    #[FunctionReturn("1: Candidate registered state. No votes, no result, no cache.\n2: Voting registration phase. Pairwise cache can exist thanks to dynamic computation if voting phase continue after the first get result. But method result never exist.\n3: Result phase: Some method result may exist, pairwise exist. An election will return to Phase 2 if votes are added or modified dynamically.")]
+    #[Related("Election::setStateToVote")]
     public function getState () : int
     {
         return $this->_State;
     }
 
     // Close the candidate config, be ready for voting (optional)
     #[PublicAPI]
+    #[Description("Force the election to get back to state 2. See Election::getState.\nIt is not necessary to use this method. The election knows how to manage its phase changes on its own. But it is a way to clear the cache containing the results of the methods.\n\nIf you are on state 1 (candidate registering), it's will close this state and prepare election to get firsts votes.\nIf you are on state 3. The method result cache will be clear, but not the pairwise. Which will continue to be updated dynamically.")]
+    #[FunctionReturn("Always True.")]
+    #[Related("Election::getState")]
     public function setStateToVote () : bool
     {
         if ( $this->_State === 1 ) :