fix: PHPDocs

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

src/Command/GitIgnoreCommand.php

@@ -40,6 +40,9 @@
  */
 final class GitIgnoreCommand extends AbstractCommand
 {
+    /**
+     * @param WriterInterface $writer the writer component for handling .gitignore file writing
+     */
     private readonly WriterInterface $writer;
 
     /**

src/GitIgnore/Classifier.php

@@ -21,18 +21,46 @@
 use function Safe\preg_match;
 
 /**
- * Classifies .gitignore entries as directories or files.
+ * Classifies .gitignore entries as directory-oriented or file-oriented patterns.
+ *
+ * This classifier SHALL inspect a raw .gitignore entry and determine whether the
+ * entry expresses directory semantics or file semantics. Implementations MUST
+ * preserve deterministic classification for identical inputs. Blank entries and
+ * comment entries MUST be treated as file-oriented values to avoid incorrectly
+ * inferring directory intent where no effective pattern exists.
  */
 final class Classifier implements ClassifierInterface
 {
+    /**
+     * Represents a classification result indicating directory semantics.
+     *
+     * This constant MUST be returned when an entry clearly targets a directory,
+     * such as entries ending with a slash or patterns that imply directory
+     * traversal.
+     */
     private const string DIRECTORY = 'directory';
 
+    /**
+     * Represents a classification result indicating file semantics.
+     *
+     * This constant MUST be returned when an entry does not clearly express
+     * directory semantics, including blank values and comment lines.
+     */
     private const string FILE = 'file';
 
     /**
-     * @param string $entry
+     * Classifies a .gitignore entry as either a directory or a file pattern.
      *
-     * @return string
+     * The provided entry SHALL be normalized with trim() before any rule is
+     * evaluated. Empty entries and comment entries MUST be classified as files.
+     * Entries ending with "/" MUST be classified as directories. Patterns that
+     * indicate directory traversal or wildcard directory matching SHOULD also be
+     * classified as directories.
+     *
+     * @param string $entry The raw .gitignore entry to classify.
+     *
+     * @return string The classification result. The value MUST be either
+     *                self::DIRECTORY or self::FILE.
      */
     public function classify(string $entry): string
     {
@@ -66,19 +94,32 @@ public function classify(string $entry): string
     }
 
     /**
-     * @param string $entry
+     * Determines whether the given .gitignore entry represents a directory pattern.
+     *
+     * This method MUST delegate the effective classification to classify() and
+     * SHALL return true only when the resulting classification is
+     * self::DIRECTORY.
      *
-     * @return bool
+     * @param string $entry The raw .gitignore entry to evaluate.
+     *
+     * @return bool true when the entry is classified as a directory pattern;
+     *              otherwise, false
      */
     public function isDirectory(string $entry): bool
     {
         return self::DIRECTORY === $this->classify($entry);
     }
 
     /**
-     * @param string $entry
+     * Determines whether the given .gitignore entry represents a file pattern.
+     *
+     * This method MUST delegate the effective classification to classify() and
+     * SHALL return true only when the resulting classification is self::FILE.
+     *
+     * @param string $entry The raw .gitignore entry to evaluate.
      *
-     * @return bool
+     * @return bool true when the entry is classified as a file pattern;
+     *              otherwise, false
      */
     public function isFile(string $entry): bool
     {

src/GitIgnore/ClassifierInterface.php

@@ -20,6 +20,12 @@
 
 /**
  * Defines the contract for classifying .gitignore entries.
+ *
+ * This classifier SHALL inspect a raw .gitignore entry and determine whether the
+ * entry expresses directory semantics or file semantics. Implementations MUST
+ * preserve deterministic classification for identical inputs. Blank entries and
+ * comment entries MUST be treated as file-oriented values to avoid incorrectly
+ * inferring directory intent where no effective pattern exists.
  */
 interface ClassifierInterface
 {

src/GitIgnore/GitIgnore.php

@@ -32,8 +32,10 @@
 final readonly class GitIgnore implements GitIgnoreInterface
 {
     /**
-     * @param list<string> $entries the .gitignore entries
+     * Initializes a GitIgnore instance with the given path and entries.
+     *
      * @param string $path the file system path to the .gitignore file
+     * @param list<string> $entries the .gitignore entries
      */
     public function __construct(
         public string $path,

src/GitIgnore/Merger.php

@@ -20,21 +20,51 @@
 
 /**
  * Merges, deduplicates, and sorts .gitignore entries.
+ *
+ * This service SHALL combine canonical and project-specific .gitignore
+ * definitions into a single normalized result. The resulting entry list MUST
+ * exclude blank lines and comment lines from the merged output, MUST remove
+ * duplicate entries, and MUST group directory entries before file entries.
+ * Directory and file groups SHALL be sorted independently in ascending string
+ * order to provide deterministic output.
  */
 final readonly class Merger implements MergerInterface
 {
     /**
-     * @param ClassifierInterface $classifier
+     * Initializes the merger with a classifier implementation.
+     *
+     * The classifier MUST be capable of determining whether a normalized
+     * .gitignore entry represents a directory or a file pattern. When no
+     * classifier is provided, a default Classifier instance SHALL be used.
+     *
+     * @param ClassifierInterface $classifier the classifier responsible for
+     *                                        distinguishing directory entries
+     *                                        from file entries during merging
      */
     public function __construct(
         private ClassifierInterface $classifier = new Classifier()
     ) {}
 
     /**
-     * @param GitIgnoreInterface $canonical
-     * @param GitIgnoreInterface $project
+     * Merges canonical and project .gitignore entries into a normalized result.
+     *
+     * The implementation MUST combine entries from both sources, MUST remove
+     * duplicates, and MUST ignore blank or commented entries after trimming.
+     * Entries identified as directories SHALL be collected separately from file
+     * entries. Each group MUST be sorted using string comparison, and directory
+     * entries MUST appear before file entries in the final result.
+     *
+     * The returned GitIgnore instance SHALL preserve the project path provided by
+     * the $project argument.
+     *
+     * @param GitIgnoreInterface $canonical The canonical .gitignore source whose
+     *                                      entries provide the shared baseline.
+     * @param GitIgnoreInterface $project The project-specific .gitignore source
+     *                                    whose path MUST be preserved in the
+     *                                    merged result.
      *
-     * @return GitIgnoreInterface
+     * @return GitIgnoreInterface A new merged .gitignore representation containing
+     *                            normalized, deduplicated, and ordered entries.
      */
     public function merge(GitIgnoreInterface $canonical, GitIgnoreInterface $project): GitIgnoreInterface
     {

src/GitIgnore/MergerInterface.php

@@ -20,6 +20,13 @@
 
 /**
  * Defines the contract for merging .gitignore entries.
+ *
+ * This service SHALL combine canonical and project-specific .gitignore
+ * definitions into a single normalized result. The resulting entry list MUST
+ * exclude blank lines and comment lines from the merged output, MUST remove
+ * duplicate entries, and MUST group directory entries before file entries.
+ * Directory and file groups SHALL be sorted independently in ascending string
+ * order to provide deterministic output.
  */
 interface MergerInterface
 {

src/GitIgnore/Reader.php

@@ -18,14 +18,25 @@
 
 namespace FastForward\DevTools\GitIgnore;
 
+/**
+ * Reads .gitignore files and returns domain representations for them.
+ *
+ * This reader SHALL provide a minimal abstraction for loading a .gitignore file
+ * from a filesystem path. The implementation MUST delegate file parsing to the
+ * GitIgnore value object and MUST return a GitIgnoreInterface-compatible result.
+ */
 final class Reader implements ReaderInterface
 {
     /**
-     * Reads a .gitignore file from the specified path.
+     * Reads a .gitignore file from the specified filesystem path.
+     *
+     * The provided path MUST reference a readable .gitignore file. This method
+     * SHALL delegate object creation to GitIgnore::fromFile() and MUST return
+     * the resulting GitIgnoreInterface implementation.
      *
-     * @param string $gitignorePath the path to the .gitignore file
+     * @param string $gitignorePath The filesystem path to the .gitignore file.
      *
-     * @return GitIgnoreInterface the GitIgnore instance
+     * @return GitIgnoreInterface The loaded .gitignore representation.
      */
     public function read(string $gitignorePath): GitIgnoreInterface
     {

src/GitIgnore/ReaderInterface.php

@@ -18,14 +18,26 @@
 
 namespace FastForward\DevTools\GitIgnore;
 
+/**
+ * Defines the contract for reading .gitignore files from a storage location.
+ *
+ * Implementations MUST load a .gitignore resource from the provided filesystem
+ * path and SHALL return a GitIgnoreInterface representation of its contents.
+ * Implementations SHOULD delegate parsing and normalization responsibilities to
+ * a dedicated domain object or parser when appropriate.
+ */
 interface ReaderInterface
 {
     /**
-     * Reads a .gitignore file from the specified path.
+     * Reads a .gitignore file from the specified filesystem path.
+     *
+     * The provided path MUST identify a readable .gitignore file. Implementations
+     * SHALL return a GitIgnoreInterface instance representing the contents read
+     * from that path.
      *
-     * @param string $gitignorePath the path to the .gitignore file
+     * @param string $gitignorePath The filesystem path to the .gitignore file.
      *
-     * @return GitIgnoreInterface the GitIgnore instance
+     * @return GitIgnoreInterface The loaded .gitignore representation.
      */
     public function read(string $gitignorePath): GitIgnoreInterface;
 }

src/GitIgnore/Writer.php

@@ -21,19 +21,37 @@
 use Symfony\Component\Filesystem\Filesystem;
 
 /**
- * Renders and writes the normalized .gitignore file.
+ * Renders and persists normalized .gitignore content.
+ *
+ * This writer SHALL transform a GitIgnoreInterface representation into the
+ * textual format expected by a .gitignore file and MUST persist that content to
+ * the target path exposed by the provided object. Implementations MUST write a
+ * trailing line feed to ensure consistent file formatting.
  */
 final readonly class Writer implements WriterInterface
 {
     /**
-     * @param Filesystem $filesystem
+     * Creates a writer with the filesystem dependency used for persistence.
+     *
+     * The provided filesystem implementation MUST support writing file contents
+     * to the target path returned by a GitIgnoreInterface instance.
+     *
+     * @param Filesystem $filesystem The filesystem service responsible for
+     *                               writing the rendered .gitignore content.
      */
     public function __construct(
         private Filesystem $filesystem
     ) {}
 
     /**
-     * @param GitIgnoreInterface $gitignore
+     * Writes the normalized .gitignore entries to the target file path.
+     *
+     * The implementation SHALL join all entries using a Unix line feed and MUST
+     * append a final trailing line feed to the generated content. The resulting
+     * content MUST be written to the path returned by $gitignore->path().
+     *
+     * @param GitIgnoreInterface $gitignore The .gitignore representation whose
+     *                                      path and entries SHALL be written.
      *
      * @return void
      */

src/GitIgnore/WriterInterface.php

@@ -19,14 +19,24 @@
 namespace FastForward\DevTools\GitIgnore;
 
 /**
- * Defines the contract for writing .gitignore files.
+ * Defines the contract for writing .gitignore representations to persistent storage.
+ *
+ * Implementations MUST persist the entries exposed by a GitIgnoreInterface
+ * instance to its associated path. Implementations SHALL preserve the semantic
+ * ordering of entries provided by the input object and SHOULD write content in a
+ * format compatible with standard .gitignore files.
  */
 interface WriterInterface
 {
     /**
-     * Writes the GitIgnore content to its associated file path.
+     * Writes the GitIgnore content to its associated filesystem path.
+     *
+     * The provided GitIgnoreInterface instance MUST contain the target path and
+     * the entries to be written. Implementations SHALL persist that content to
+     * the associated location represented by the given object.
      *
-     * @param GitIgnoreInterface $gitignore the GitIgnore instance to write
+     * @param GitIgnoreInterface $gitignore The .gitignore representation to
+     *                                      write to persistent storage.
      *
      * @return void
      */