gistfile1.txt

Consider prioritizing writing better/usefull PHPDoc instead of the current way.

currently

<?php

/**
 * Class Repository
 *
 * @link    http://pyrocms.com/
 * @author  PyroCMS, Inc. <support@pyrocms.com>
 * @author  Ryan Thompson <ryan@pyrocms.com>
 */
class Repository implements RepositoryInterface
{
    use Macroable;
    use HasMemory;
    use FiresCallbacks;

    /**
     * The stream instance.
     *
     * @var Stream
     */
    protected $stream;

    /**
     * Create a new Repository instance.
     *
     * @param Stream $stream
     */
    public function __construct(Stream $stream)
    {
        $this->stream = $stream;
    }
}

The most relevant issues:

• The description on the constructor is redundant
• The method is fully type-hinted, the parameters are redundant
• Similary the docblock description on the current way property is redundant.
• References are much clearer using fqcn's.
  • When browsing the code, it tells you exactly what class it is, you dont have to scroll to top anymore.
  • It also directly affects ide behaviour, documentation generatation and xml data output.

proposal

<?php

/**
 * The Repository class wraps a {@link https://pyrocms.com/documentation/Streams stream} and makes it...
 *
 * This is the default way of... [long, proper description, Some extra notes why this is used, maby some @see and/or @link to other relevant information]
 *
 * @example
 * ```php
 * $repository = new Repository($stream)
 * $items = $repository->all(); // returns collection
 * ```
 *
 * @link https://pyrocms.com/documentation/Repositories Documentation on Repositories
 * @author  PyroCMS, Inc. <support@pyrocms.com>
 * @author  Ryan Thompson <ryan@pyrocms.com>
 */
class Repository implements RepositoryInterface
{
    use Macroable;
    use HasMemory;
    use FiresCallbacks;

    /** @var \Anomaly\Streams\Platform\Stream\Stream */
    protected $stream;

    public function __construct(Stream $stream)
    {
        $this->stream = $stream;
    }
}

• Decreases time spend on generating/maintaining redundant PHPDoc
• Improves readability
• Clearly explains what each class does and why it does it. Could even throw in one or more examples
• With a bit of cleverness you could (using the generated XML from PHPDoc) tie this in with documentation,