Skip to content

Skip Missing doc comment when signature is fully typed#432

Open
dereuromark wants to merge 1 commit into5.xfrom
fix/function-comment-missing-with-types
Open

Skip Missing doc comment when signature is fully typed#432
dereuromark wants to merge 1 commit into5.xfrom
fix/function-comment-missing-with-types

Conversation

@dereuromark
Copy link
Copy Markdown
Member

@dereuromark dereuromark commented Apr 12, 2026

Summary

The CakePHP.Commenting.FunctionComment.Missing sniff currently flags every function without a docblock, even when the signature already expresses all type information natively. With constructor property promotion this is especially noisy:

final readonly class TenancySlice
{
    public function __construct(
        public string $x,
        public Decimal $y,
        public int $z,
    ) {
    }
}

Every parameter is already visibility-, type- and name-declared inline; a docblock would be pure redundancy.

This PR teaches the sniff to skip the `Missing` error when the function signature carries full native type information:

  • `__construct` — skipped if every parameter has a native type (constructors cannot declare a return type).
  • Any other function — skipped if it has a native return type and every parameter has a native type.

Functions that still lack types (untyped params, missing return types) continue to require a docblock, so legacy code is unaffected.

Other existing checks (spacing after docblock, `@throws` validation, etc.) are unchanged and still run whenever a docblock is present.

A function with a native return type (or a constructor) and native type
declarations on every parameter expresses all its type information in
the signature. Requiring a docblock in that case produces noise,
especially for constructors that use property promotion where every
parameter is already visibility- and type-declared inline.

The sniff now skips the 'Missing doc comment' error when:

- the function is __construct and every parameter has a native type, or
- the function has a native return type and every parameter has a
  native type.

Functions that still lack types (legacy code, callbacks with mixed
arguments) continue to require a docblock.
@ADmad
Copy link
Copy Markdown
Member

ADmad commented Apr 13, 2026

While skipping argument description is fine, every public method should have a general description IMO.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants