Added phpdocs

README.md

@@ -40,7 +40,7 @@ $rule = $matcher->match($relative_path);
 ## TODO
 
 - [x] Add comments to the structure
-- [ ] Complete phpdocs
+- [x] Complete phpdocs
 - [ ] Add error checking on `match` to normalize or reject impossible patterns (i.e. "" and "/...")
 - [ ] Explain how `AutomataMatcher` works in this file.
 - [x] Should I support whitespace escaping in patterns?
@@ -52,6 +52,7 @@ $rule = $matcher->match($relative_path);
 - [x] Remove ext-json from requires.
 - [x] Add ext-ctype to requires.
 - [x] Convert json tests to PHP arrays.
+- [ ] Add a command line tool for dot-renderer
 
 ## Author(s)
 

src/AutomataMatcher.php

@@ -5,11 +5,23 @@
 use Kellegous\CodeOwners\AutomataMatcher\State;
 use Kellegous\CodeOwners\AutomataMatcher\Token;
 
+/**
+ * A RuleMatcher that combines all the patterns into a single automata.
+ */
 final class AutomataMatcher implements RuleMatcher
 {
+    /**
+     * This is the start state for the automata.
+     *
+     * @var State
+     */
     private State $start;
 
     /**
+     * The full collection of rules from the Owners instance. The NFA keeps the index of
+     * rules instead of a reference to the rules themselves since the index provides a straight-forward
+     * way to honor the last-match-wins rule (the largest of the matching indexes wins).
+     *
      * @var Rule[]
      */
     private array $rules;
@@ -27,6 +39,8 @@ private function __construct(
     }
 
     /**
+     * Builds a new AutomataMatcher from the given rules.
+     *
      * @param iterable<Rule> $rules
      * @return self
      */
@@ -76,6 +90,14 @@ private static function parsePattern(Pattern $pattern): array
         return $tokens;
     }
 
+    /**
+     * Strangely, a pattern is absolute not only if it starts with a slash,
+     * but also if it contains a wildcard.
+     *
+     * @param string $pattern
+     *
+     * @return bool
+     */
     private static function isAbsolute(string $pattern): bool
     {
         $ix = strpos($pattern, '/');
@@ -132,6 +154,8 @@ private static function parseToken(
     }
 
     /**
+     * @inerhitDoc
+     * @Override
      * @param string $path
      * @return Rule|null
      */
@@ -145,6 +169,8 @@ public function match(string $path): ?Rule
     }
 
     /**
+     * Used to return an internal representation of the automata for debugging purposes.
+     *
      * @return array{nodes: array<string, int>, edges: array{from: string, to: string, label: string}[]}
      *
      * @internal

src/AutomataMatcher/DotRenderer.php

@@ -4,9 +4,16 @@
 
 use Kellegous\CodeOwners\AutomataMatcher;
 
+/**
+ * Intended for debugging, this class will emit a graphviz dot file to visualize
+ * the state machine used to match patterns in an AutomataMatcher.
+ */
 final class DotRenderer
 {
     /**
+     * Generate a graphviz dot file from the given AutomataMatcher. This can be
+     * rendered using the dot command.
+     *
      * @param AutomataMatcher $matcher
      * @return string
      */

src/AutomataMatcher/State.php

@@ -1,27 +1,44 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Kellegous\CodeOwners\AutomataMatcher;
 
 use InvalidArgumentException;
 
+/**
+ * Represents a state in the NFA.
+ * @Internal
+ */
 final class State
 {
     /**
+     * The index of the rule. We call this priority because we choose the highest
+     * priority state (the last rule) to choose the best match.
+     *
      * @var int
      */
     private int $priority = -1;
 
     /**
+     * The key is a regex pattern for the segment and the value is the next state.
+     *
      * @var array<string, State>
      */
     private array $edges = [];
 
     /**
+     * A recursive state is a special ** state which is one that has a self-referencing
+     * epsilon state.
+     *
      * @var bool
      */
     private bool $isRecursive;
 
     /**
+     * Create a new state. If the state is a terminating ** state, then it will
+     * be considered recursive.
+     *
      * @param bool $isRecursive
      */
     public function __construct(bool $isRecursive = false)
@@ -30,6 +47,8 @@ public function __construct(bool $isRecursive = false)
     }
 
     /**
+     * Add the states associated with the tokens of a parsed pattern.
+     *
      * @param Token[] $tokens
      * @param int $priority
      * @return void
@@ -65,6 +84,9 @@ public function addTokens(
     }
 
     /**
+     * Find the highest priority match for the given path. Note that a return value
+     * of -1 indicates that no match was found.
+     *
      * @param string[] $path
      * @return int
      */
@@ -94,6 +116,8 @@ public function match(array $path): int
     }
 
     /**
+     * Used to return an internal representation of the automata for debugging purposes.
+     *
      * @param array<string, int> $nodes
      * @param array{from:int, to: int, label:string}[] $edges
      * @return void

src/AutomataMatcher/Token.php

@@ -4,12 +4,30 @@
 
 namespace Kellegous\CodeOwners\AutomataMatcher;
 
+/**
+ * Represents a "segment" of a pattern. Each pattern consists of a number of
+ * tokens separated by "/" characters. This class holds the raw string
+ * representation of that segment as well as the regular expression that matches
+ * that segment.
+ *
+ * @internal
+ */
 final class Token
 {
+    /**
+     * @var string
+     */
     private string $pattern;
 
+    /**
+     * @var string
+     */
     private string $regex;
 
+    /**
+     * @param string $pattern
+     * @param string $regex
+     */
     public function __construct(
         string $pattern,
         string $regex
@@ -18,11 +36,17 @@ public function __construct(
         $this->regex = $regex;
     }
 
+    /**
+     * @return string
+     */
     public function getPattern(): string
     {
         return $this->pattern;
     }
 
+    /**
+     * @return string
+     */
     public function getRegex(): string
     {
         return $this->regex;

src/Blank.php

@@ -4,6 +4,9 @@
 
 namespace Kellegous\CodeOwners;
 
+/**
+ * Represents a blank line in the code owners file.
+ */
 final class Blank implements Entry
 {
     private SourceInfo $sourceInfo;

src/Comment.php

@@ -4,12 +4,26 @@
 
 namespace Kellegous\CodeOwners;
 
+/**
+ * Represents a comment in the code owners file.
+ */
 final class Comment implements Entry
 {
+    /**
+     * The text of the comment including the leading `#`.
+     * @var string
+     */
     private string $text;
 
+    /**
+     * @var SourceInfo
+     */
     private SourceInfo $sourceInfo;
 
+    /**
+     * @param string $text
+     * @param SourceInfo $sourceInfo
+     */
     public function __construct(
         string $text,
         SourceInfo $sourceInfo
@@ -19,6 +33,7 @@ public function __construct(
     }
 
     /**
+     * @inheritDoc
      * @Override
      * @return SourceInfo
      */
@@ -28,6 +43,7 @@ public function getSourceInfo(): SourceInfo
     }
 
     /**
+     * #inheritDoc
      * @Override
      * @return string
      */

src/Owners.php

@@ -6,6 +6,9 @@
 
 use Iterator;
 
+/**
+ * Represents the contents of a code owners file.
+ */
 final class Owners
 {
     /**
@@ -23,6 +26,8 @@ private function __construct(
     }
 
     /**
+     * Parse the contents of a code owners file.
+     *
      * @param string $filename
      * @return self
      * @throws ParseException
@@ -109,6 +114,8 @@ private static function readLinesFrom(string $filename): iterable
     }
 
     /**
+     * Parse the contents of a code owners file as a string.
+     *
      * @param string $content
      * @param string|null $filename
      * @return self
@@ -129,6 +136,9 @@ public static function fromString(
     }
 
     /**
+     * Get only the rules that are present in the code owners structure. This omits
+     * blank lines and comments.
+     *
      * @return iterable<Rule>
      */
     public function getRules(): iterable
@@ -141,6 +151,8 @@ public function getRules(): iterable
     }
 
     /**
+     * Get all entries from the code owners file.
+     *
      * @return iterable<Entry>
      */
     public function getEntries(): iterable

src/ParseException.php

@@ -6,6 +6,9 @@
 
 use Exception;
 
+/**
+ * Thrown when the contents of an owners file cannot be parsed.
+ */
 final class ParseException extends Exception
 {
 }

src/Pattern.php

@@ -6,18 +6,31 @@
 
 use Closure;
 
+/**
+ * Represents a file pattern part of a rule in a code owners file.
+ */
 final class Pattern
 {
     /**
      * @var string
      */
     private string $pattern;
 
+    /**
+     * @param string $pattern
+     */
     private function __construct(string $pattern)
     {
         $this->pattern = $pattern;
     }
 
+    /**
+     * Parse the pattern from a string to a Pattern instance.
+     *
+     * @param string $pattern
+     * @return self
+     * @throws ParseException
+     */
     public static function parse(string $pattern): self
     {
         if (strpos($pattern, '***') !== false || $pattern === '') {
@@ -26,12 +39,19 @@ public static function parse(string $pattern): self
         return new self($pattern);
     }
 
+    /**
+     * Get the string representation of the pattern.
+     *
+     * @return string
+     */
     public function toString(): string
     {
         return $this->pattern;
     }
 
     /**
+     * Get a matcher function for the pattern.
+     *
      * @return Closure(string):bool
      */
     public function getMatcher(): Closure
@@ -46,6 +66,12 @@ public function getMatcher(): Closure
         };
     }
 
+    /**
+     * Create a regular expression from a pattern.
+     *
+     * @param string $pattern
+     * @return string
+     */
     private static function toRegexp(string $pattern): string
     {
         if ($pattern === '/') {