Skip Missing doc comment when signature is fully typed#432
Open
dereuromark wants to merge 1 commit into5.xfrom
Open
Skip Missing doc comment when signature is fully typed#432dereuromark wants to merge 1 commit into5.xfrom
dereuromark wants to merge 1 commit into5.xfrom
Conversation
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.
Member
|
While skipping argument description is fine, every public method should have a general description IMO. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
CakePHP.Commenting.FunctionComment.Missingsniff 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: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:
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.