如何在phpDocumentor中抑制get/set方法的‘无摘要’错误？

Great question—dealing with redundant docblocks for getters/setters is a common pain point with phpDocumentor, especially when you already have clear documentation on your properties. Let’s break down the best DRY-compliant solutions to fix those "No summary" errors without repeating yourself:

1. Use Class-Level @method Annotations #

This is my go-to solution because it centralizes getter/setter summaries in your class docblock, keeping method docblocks minimal. phpDocumentor recognizes class-level @method tags as official documentation for your methods, so you won’t get summary errors anymore.

Here’s how to implement it:

/**
 * Class Contact
 * 
 * @method string getFirstName() Returns the contact's first name
 * @method void setFirstName(string $firstName) Sets the contact's first name
 * // Add similar lines for other getter/setter pairs
 */
class Contact {
    /** @var string $firstName contact's first name */
    protected $firstName;

    /** @return string */
    public function getFirstName() {
        return $this->firstName;
    }

    /** @param string $firstName */
    public function setFirstName($firstName) {
        $this->firstName = $firstName;
    }
}

• The class-level @method lines provide the required summary for each getter/setter.
• Your method docblocks only need to keep the @return/@param tags (you could even omit them if you want, since the @method tag already defines return types/parameters—though keeping them helps with IDE autocompletion).

2. Ignore Getter/Setter Summary Errors (Quick Fix) #

If you don’t want to add extra annotations and just want to suppress the errors, you can configure phpDocumentor to ignore summary checks for methods matching the get[A-Z]/set[A-Z] pattern.

Create a phpdoc.xml configuration file in your project root with this content:

<?xml version="1.0" encoding="UTF-8"?>
<phpdoc>
    <parser>
        <ignore>
            <error type="no-summary" pattern=".*get[A-Z].*"/>
            <error type="no-summary" pattern=".*set[A-Z].*"/>
        </ignore>
    </parser>
    <!-- Add other config (like target directory) as needed -->
</phpdoc>

Run phpDocumentor with this config using:

phpdoc -c phpdoc.xml

Note: This hides the errors but doesn’t add actual summaries to your documentation. Use this only if you’re okay with your getter/setters having empty summaries in the final output.

3. Customize the phpDocumentor Template (Advanced) #

For a fully automated solution that pulls summaries directly from your property docblocks, you can modify phpDocumentor’s default template. This requires some familiarity with Smarty templates (which phpDocumentor uses).

The core idea is to:

• In the template that renders method documentation, check if the method name starts with get or set.
• Extract the property name (e.g., FirstName → firstName).
• Look up the property’s docblock and use its description to auto-generate the method summary (e.g., "Returns the contact's first name" for getFirstName()).

This is more work upfront but pays off if you have dozens of getter/setter pairs across multiple classes. You can find the default template files in phpDocumentor’s installation directory under data/templates.

Out of these options, the class-level @method approach strikes the best balance between DRY principles and clear documentation—it keeps your code clean while ensuring phpDocumentor generates complete, error-free docs.

内容的提问来源于stack exchange，提问作者Jason Aller