Better explain the code using actual type hints

src/Chances/Chance.php

@@ -1,7 +1,9 @@
 <?php
+declare(strict_types=1);
+
 namespace Scientist\Chances;
 
 interface Chance
 {
-    public function shouldRun();
+    public function shouldRun(): bool;
 }

src/Chances/StandardChance.php

@@ -1,14 +1,19 @@
 <?php
+declare(strict_types=1);
+
 namespace Scientist\Chances;
 
 class StandardChance implements Chance
 {
+    /**
+     * @var int
+     */
     private $percentage = 100;
 
     /**
      * Determine whether or not the experiment should run
      */
-    public function shouldRun()
+    public function shouldRun(): bool
     {
         if ($this->percentage == 0) {
             return false;
@@ -19,19 +24,12 @@ public function shouldRun()
         return $random <= $this->percentage;
     }
 
-    /**
-     * @return int
-     */
-    public function getPercentage()
+    public function getPercentage(): int
     {
         return $this->percentage;
     }
 
-    /**
-     * @param int $percentage
-     * @return $this
-     */
-    public function setPercentage($percentage)
+    public function setPercentage(int $percentage): self
     {
         $this->percentage = $percentage;
 

src/Experiment.php

@@ -1,7 +1,9 @@
 <?php
+declare(strict_types=1);
 
 namespace Scientist;
 
+use Scientist\Report;
 use Scientist\Chances\Chance;
 use Scientist\Chances\StandardChance;
 use Scientist\Matchers\Matcher;
@@ -41,7 +43,7 @@ class Experiment
     /**
      * Trial callbacks.
      *
-     * @var array
+     * @var callable[]
      */
     protected $trials = [];
 
@@ -75,11 +77,8 @@ class Experiment
 
     /**
      * Create a new experiment.
-     *
-     * @param string                $name
-     * @param \Scientist\Laboratory $laboratory
      */
-    public function __construct($name, Laboratory $laboratory)
+    public function __construct(string $name, Laboratory $laboratory)
     {
         $this->name = $name;
         $this->laboratory = $laboratory;
@@ -89,33 +88,26 @@ public function __construct($name, Laboratory $laboratory)
 
     /**
      * Fetch the experiment name.
-     *
-     * @return string
      */
-    public function getName()
+    public function getName(): string
     {
         return $this->name;
     }
 
     /**
      * Retrieve the laboratory instance.
-     *
-     * @return \Scientist\Laboratory|null
      */
-    public function getLaboratory()
+    public function getLaboratory(): ?Laboratory
     {
         return $this->laboratory;
     }
 
     /**
      * Register a control callback.
      *
-     * @param callable $callback
      * @param mixed $context
-     *
-     * @return $this
      */
-    public function control(callable $callback, $context = null)
+    public function control(callable $callback, $context = null): self
     {
         $this->control = $callback;
         $this->controlContext = $context;
@@ -125,14 +117,15 @@ public function control(callable $callback, $context = null)
 
     /**
      * Fetch the control callback.
-     *
-     * @return callable
      */
-    public function getControl()
+    public function getControl(): callable
     {
         return $this->control;
     }
 
+    /**
+     * @return mixed
+     */
     public function getControlContext()
     {
         return $this->controlContext;
@@ -141,12 +134,9 @@ public function getControlContext()
     /**
      * Register a trial callback.
      *
-     * @param string   $name
-     * @param callable $callback
-     *
-     * @return $this
+     * @param mixed $context
      */
-    public function trial($name, callable $callback, $context = null)
+    public function trial(string $name, callable $callback, $context = null): self
     {
         $this->trials[$name] = new Trial($name, $callback, $context);
 
@@ -155,34 +145,26 @@ public function trial($name, callable $callback, $context = null)
 
     /**
      * Fetch a trial callback by name.
-     *
-     * @param string $name
-     *
-     * @return mixed
      */
-    public function getTrial($name)
+    public function getTrial(string $name): callable
     {
         return $this->trials[$name]->getCallback();
     }
 
     /**
      * Fetch an array of trial callbacks.
      *
-     * @return array
+     * @return callable[]
      */
-    public function getTrials()
+    public function getTrials(): array
     {
         return $this->trials;
     }
 
     /**
      * Set a matcher for this experiment.
-     *
-     * @param \Scientist\Matchers\Matcher $matcher
-     *
-     * @return $this
      */
-    public function matcher(Matcher $matcher)
+    public function matcher(Matcher $matcher): self
     {
         $this->matcher = $matcher;
 
@@ -191,22 +173,16 @@ public function matcher(Matcher $matcher)
 
     /**
      * Get the matcher for this experiment.
-     *
-     * @return \Scientist\Matchers\Matcher
      */
-    public function getMatcher()
+    public function getMatcher(): Matcher
     {
         return $this->matcher;
     }
 
     /**
      * Set the execution chance.
-     *
-     * @param Chances\Chance $chance
-     *
-     * @return $this
      */
-    public function chance(Chance $chance)
+    public function chance(Chance $chance): self
     {
         $this->chance = $chance;
 
@@ -215,31 +191,25 @@ public function chance(Chance $chance)
 
     /**
      * Get the execution chance.
-     *
-     * @return Chances\Chance
      */
-    public function getChance()
+    public function getChance(): Chance
     {
         return $this->chance;
     }
 
     /**
      * Determine whether an experiment should run based on chance.
-     *
-     * @return boolean
      */
-    public function shouldRun()
+    public function shouldRun(): bool
     {
         return $this->chance
             ->shouldRun();
     }
 
     /**
      * Get the experiment parameters.
-     *
-     * @return array
      */
-    public function getParams()
+    public function getParams(): array
     {
         return $this->params;
     }
@@ -258,10 +228,8 @@ public function run()
 
     /**
      * Execute the experiment and return a report.
-     *
-     * @return \Scientist\Report
      */
-    public function report()
+    public function report(): Report
     {
         $this->params = func_get_args();
 

src/Intern.php

@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 
 namespace Scientist;
 
@@ -16,12 +17,8 @@ class Intern
 {
     /**
      * Run an experiment, and retrieve the result.
-     *
-     * @param \Scientist\Experiment $experiment
-     *
-     * @return \Scientist\Report
      */
-    public function run(Experiment $experiment)
+    public function run(Experiment $experiment): Report
     {
         $control = $this->runControl($experiment);
         $trials  = $this->runTrials($experiment);
@@ -33,12 +30,8 @@ public function run(Experiment $experiment)
 
     /**
      * Run the control callback, and record its execution state.
-     *
-     * @param \Scientist\Experiment $experiment
-     *
-     * @return \Scientist\Result
      */
-    protected function runControl(Experiment $experiment)
+    protected function runControl(Experiment $experiment): Result
     {
         return (new Machine(
             $experiment->getControl(),
@@ -51,11 +44,9 @@ protected function runControl(Experiment $experiment)
     /**
      * Run trial callbacks and record their execution state.
      *
-     * @param \Scientist\Experiment $experiment
-     *
-     * @return \Scientist\Result[]
+     * @return Result[]
      */
-    protected function runTrials(Experiment $experiment)
+    protected function runTrials(Experiment $experiment): array
     {
         $executions = [];
 
@@ -74,11 +65,9 @@ protected function runTrials(Experiment $experiment)
     /**
      * Determine whether trial results match the control.
      *
-     * @param \Scientist\Matchers\Matcher $matcher
-     * @param \Scientist\Result           $control
-     * @param \Scientist\Result[]         $trials
+     * @param Result[] $trials
      */
-    protected function determineMatches(Matcher $matcher, Result $control, array $trials = [])
+    protected function determineMatches(Matcher $matcher, Result $control, array $trials = []): void
     {
         foreach ($trials as $trial) {
             if ($matcher->match($control->getValue(), $trial->getValue())) {

src/Journals/Journal.php

@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 
 namespace Scientist\Journals;
 
@@ -18,9 +19,6 @@ interface Journal
     /**
      * Dispatch a report to storage.
      *
-     * @param \Scientist\Experiment $experiment
-     * @param \Scientist\Report     $report
-     *
      * @return mixed
      */
     public function report(Experiment $experiment, Report $report);