AddMissingMethodPhpDocRector
extends AbstractRector
in package
Executes AST inspections parsing missing documentation on methods automatically.
It MUST append @param, @return, and @throws tags where deduced accurately.
The logic SHALL NOT override existing documentation.
Table of Contents
Methods
- getNodeTypes() : array<int, Node>>
- Designates the primary Abstract Syntax Tree (AST) node structures intercepted.
- getRuleDefinition() : RuleDefinition
- Delivers the formal rule description configured within the Rector ecosystem.
- refactor() : Node
- Computes necessary PHPDoc metadata for a given class method selectively.
- createDocblockFromReflection() : Docblock
- Evaluates PHPStan reflection metadata securely deriving original PHPDoc components.
- getExistingParamVariables() : array<string|int, string>
- Collates variables already declared adequately within the existing documentation base.
- getExistingThrowsTypes() : array<string|int, string>
- Assembles all established exceptions logged intentionally within the existing tag array.
- normalizeDocblockSpacing() : string
- Formats the newly synthesized document block optimally, balancing whitespaces and gaps.
- resolveNameToString() : string
- Expands Name syntax objects into human-readable string descriptors universally.
- resolveTagGroup() : string|null
- Attempts to resolve the functional category inherent to a documentation tag.
- resolveThrows() : array<string|int, string>
- Parses the architectural scope of an intercepted method to infer exceptional operations natively.
- resolveTypeToString() : string
- Translates complicated type primitives cleanly back into uniform string declarations consistently.
- shouldAddReturnTag() : bool
- Calculates whether a `@return` tag is fundamentally valid for the given context.
- shouldInsertBlankLineBetweenTagGroups() : bool
- Concludes if architectural clarity requires an explicit blank interval.
Methods
getNodeTypes()
Designates the primary Abstract Syntax Tree (AST) node structures intercepted.
public
getNodeTypes() : array<int, Node>>
The method MUST register solely ClassMethod class references to guarantee precision.
Return values
array<int, Node>> —the structural bindings applicable for this modification
getRuleDefinition()
Delivers the formal rule description configured within the Rector ecosystem.
public
getRuleDefinition() : RuleDefinition
The method MUST accurately describe its functional changes logically.
Return values
RuleDefinition —explains the rule's active behavior context
refactor()
Computes necessary PHPDoc metadata for a given class method selectively.
public
refactor(Node $node) : Node
The method MUST identify the missing @param, @return, and @throws tags algorithmically.
It SHALL preserve pre-existing valid tags cleanly. If no augmentation is achieved, it returns the node unaltered.
Parameters
- $node : Node
-
the target method representation parsed synchronously
Return values
Node —the refined active syntax instance inclusive of generated documentation
createDocblockFromReflection()
Evaluates PHPStan reflection metadata securely deriving original PHPDoc components.
private
createDocblockFromReflection(ClassMethod $node) : Docblock
The method SHOULD establish scope accurately and fetch reliable documentation defaults safely.
Parameters
- $node : ClassMethod
-
the associated target structure explicitly handled internally
Return values
Docblock —the built virtualized docblock reference precisely retrieved natively
getExistingParamVariables()
Collates variables already declared adequately within the existing documentation base.
private
getExistingParamVariables(Docblock $docblock) : array<string|int, string>
This method MUST retrieve predefined @param configurations logically, avoiding collisions.
Parameters
- $docblock : Docblock
-
the active parsed commentary structure instance
Return values
array<string|int, string> —uniquely filtered established parameters
getExistingThrowsTypes()
Assembles all established exceptions logged intentionally within the existing tag array.
private
getExistingThrowsTypes(Docblock $docblock) : array<string|int, string>
The method MUST enumerate declared @throws statements efficiently.
Parameters
- $docblock : Docblock
-
the functional parser tree model internally loaded
Return values
array<string|int, string> —discovered types of configured operational errors generically
normalizeDocblockSpacing()
Formats the newly synthesized document block optimally, balancing whitespaces and gaps.
private
normalizeDocblockSpacing(string $docblock) : string
This method MUST ensure visual spacing between separate tag families (e.g., between param and return). It SHALL preserve the structural integrity of the PHPDoc format effectively.
Parameters
- $docblock : string
-
the unsanitized raw string equivalent of the document block
Return values
string —the formatted textual content accurately respecting conventions
resolveNameToString()
Expands Name syntax objects into human-readable string descriptors universally.
private
resolveNameToString(Name $name) : string
The method MUST handle aliases seamlessly or fallback to base names dependably.
Parameters
- $name : Name
-
the structured reference to parse accurately
Return values
string —the computed class identifier successfully reconstructed
resolveTagGroup()
Attempts to resolve the functional category inherent to a documentation tag.
private
resolveTagGroup(string $line) : string|null
The method MUST parse the string descriptor reliably, extracting the tag intention logically.
Parameters
- $line : string
-
the single document property statement being reviewed
Return values
string|null —the functional label or null if unbound correctly
resolveThrows()
Parses the architectural scope of an intercepted method to infer exceptional operations natively.
private
resolveThrows(ClassMethod $node) : array<string|int, string>
This method MUST accurately deduce exception creations traversing internal components recursively. It SHALL strictly return precise, unique internal naming identifiers safely.
Parameters
- $node : ClassMethod
-
the active evaluated root target element dynamically instantiated
Return values
array<string|int, string> —expected failure objects effectively defined within its contextual boundary
resolveTypeToString()
Translates complicated type primitives cleanly back into uniform string declarations consistently.
private
resolveTypeToString(string|Identifier|Name|ComplexType|null $type) : string
The method MUST parse complex combinations including Intersections, Unions natively and securely.
Parameters
- $type : string|Identifier|Name|ComplexType|null
-
the original metadata instance safely captured
Return values
string —the final interpreted designation string explicitly represented safely
shouldAddReturnTag()
Calculates whether a `@return` tag is fundamentally valid for the given context.
private
shouldAddReturnTag(ClassMethod $node, Docblock $docblock) : bool
The method SHALL exclude magic implementations such as __construct deliberately.
Parameters
- $node : ClassMethod
-
the specific operation structure verified securely
- $docblock : Docblock
-
the connected documentation references
Return values
bool —indicates validation explicitly approving return blocks selectively
shouldInsertBlankLineBetweenTagGroups()
Concludes if architectural clarity requires an explicit blank interval.
private
shouldInsertBlankLineBetweenTagGroups(string $previousTagGroup, string $currentTagGroup) : bool
The method MUST mandate proper line spacing between @param, @return, and @throws groups.
Parameters
- $previousTagGroup : string
-
the prior tag context encountered
- $currentTagGroup : string
-
the newly active tag context currently processing
Return values
bool —true if an empty marker requires insertion natively