improved PHPDoc descriptions

Author: dg

src/PhpGenerator/ClassLike.php

@@ -12,7 +12,7 @@
 
 
 /**
- * Base definition of class, interface, trait or enum type.
+ * Base for class, interface, trait, and enum definitions.
  */
 abstract class ClassLike
 {
@@ -35,7 +35,11 @@ abstract class ClassLike
 	private ?string $name;
 
 
-	/** @param class-string|object  $class */
+	/**
+	 * Creates an instance from a class reflection.
+	 * @param  class-string|object  $class
+	 * @param  bool  $withBodies  load method bodies (requires nikic/php-parser)
+	 */
 	public static function from(string|object $class, bool $withBodies = false): static
 	{
 		$instance = (new Factory)
@@ -50,6 +54,9 @@ public static function from(string|object $class, bool $withBodies = false): sta
 	}
 
 
+	/**
+	 * Creates an instance by parsing PHP source code containing a class definition.
+	 */
 	public static function fromCode(string $code): static
 	{
 		$instance = (new Factory)
@@ -112,6 +119,9 @@ public function getName(): ?string
 	}
 
 
+	/**
+	 * Returns the fully qualified name including namespace, or just the short name if no namespace is set.
+	 */
 	public function getFullName(): ?string
 	{
 		return $this->name && ($namespace = $this->namespace?->getName())

src/PhpGenerator/ClassManipulator.php

@@ -11,6 +11,9 @@
 use const PHP_VERSION_ID;
 
 
+/**
+ * Provides advanced manipulation of a ClassType, such as inheriting members from parent classes or implementing interfaces.
+ */
 final class ClassManipulator
 {
 	public function __construct(
@@ -20,7 +23,8 @@ public function __construct(
 
 
 	/**
-	 * Inherits property from parent class.
+	 * Copies a property from a parent class into this class for overriding.
+	 * @throws Nette\InvalidStateException if the property already exists or the parent is not set
 	 */
 	public function inheritProperty(string $name, bool $returnIfExists = false): Property
 	{
@@ -48,7 +52,8 @@ public function inheritProperty(string $name, bool $returnIfExists = false): Pro
 
 
 	/**
-	 * Inherits method from parent class or interface.
+	 * Copies a method from a parent class or interface into this class for overriding.
+	 * @throws Nette\InvalidStateException if the method already exists or the parent is not set
 	 */
 	public function inheritMethod(string $name, bool $returnIfExists = false): Method
 	{
@@ -75,8 +80,8 @@ public function inheritMethod(string $name, bool $returnIfExists = false): Metho
 
 
 	/**
-	 * Implements all methods from the given interface or abstract class.
-	 * @param class-string  $name
+	 * Adds stub implementations for all abstract methods and properties from the given interface or abstract class.
+	 * @param  class-string  $name
 	 */
 	public function implement(string $name): void
 	{

src/PhpGenerator/ClassType.php

@@ -132,6 +132,10 @@ public function removeImplement(string $name): static
 	}
 
 
+	/**
+	 * Adds a member to the class.
+	 * @throws Nette\InvalidStateException if the member already exists and $overwrite is false
+	 */
 	public function addMember(Method|Property|Constant|TraitUse $member, bool $overwrite = false): static
 	{
 		$name = $member->getName();

src/PhpGenerator/Closure.php

@@ -20,7 +20,10 @@ final class Closure
 	private array $uses = [];
 
 
-	/** @param \Closure(): mixed  $closure */
+	/**
+	 * Creates an instance from a closure reflection.
+	 * @param  \Closure(): mixed  $closure
+	 */
 	public static function from(\Closure $closure): self
 	{
 		return (new Factory)->fromFunctionReflection(new \ReflectionFunction($closure));
@@ -52,6 +55,9 @@ public function getUses(): array
 	}
 
 
+	/**
+	 * Adds a variable binding to the closure's use list.
+	 */
 	public function addUse(string $name): Parameter
 	{
 		return $this->uses[] = new Parameter($name);

src/PhpGenerator/Dumper.php

@@ -26,7 +26,8 @@ final class Dumper
 
 
 	/**
-	 * Returns a PHP representation of a variable.
+	 * Converts a value to its PHP code representation.
+	 * @param  int  $column  current column for array wrapping decisions
 	 */
 	public function dump(mixed $var, int $column = 0): string
 	{
@@ -214,7 +215,9 @@ private function dumpLiteral(Literal $var, int $level): string
 
 
 	/**
-	 * Generates PHP statement. Supports placeholders: ?  \?  $?  ->?  ::?  ...?  ...?:  ?*
+	 * Formats a PHP expression using placeholders.
+	 * Supported placeholders: ? (value), \? (literal ?), $? (variable), ->? (property access),
+	 * ::? (static access), ...? (spread array), ...?: (named spread), ?* (alias for ...?)
 	 */
 	public function format(string $statement, mixed ...$args): string
 	{

src/PhpGenerator/EnumType.php

@@ -27,13 +27,19 @@ final class EnumType extends ClassLike
 	private ?string $type = null;
 
 
+	/**
+	 * Sets the backing type of a backed enum ('int' or 'string').
+	 */
 	public function setType(?string $type): static
 	{
 		$this->type = $type;
 		return $this;
 	}
 
 
+	/**
+	 * Returns the backing type ('int' or 'string'), or null for a pure enum.
+	 */
 	public function getType(): ?string
 	{
 		return $this->type;
@@ -72,7 +78,7 @@ public function removeImplement(string $name): static
 
 
 	/**
-	 * Sets cases to enum
+	 * Replaces all cases.
 	 * @param  list<EnumCase>  $cases
 	 */
 	public function setCases(array $cases): static
@@ -94,7 +100,10 @@ public function getCases(): array
 	}
 
 
-	/** Adds case to enum */
+	/**
+	 * Adds a case to the enum.
+	 * @throws Nette\InvalidStateException if the case already exists and $overwrite is false
+	 */
 	public function addCase(string $name, string|int|Literal|null $value = null, bool $overwrite = false): EnumCase
 	{
 		if (!$overwrite && isset($this->cases[$name])) {
@@ -113,7 +122,8 @@ public function removeCase(string $name): static
 
 
 	/**
-	 * Adds a member. If it already exists, throws an exception or overwrites it if $overwrite is true.
+	 * Adds a member to the enum.
+	 * @throws Nette\InvalidStateException if the member already exists and $overwrite is false
 	 */
 	public function addMember(Method|Constant|EnumCase|TraitUse $member, bool $overwrite = false): static
 	{

src/PhpGenerator/Factory.php

@@ -14,7 +14,7 @@
 
 
 /**
- * Creates a representations based on reflection or source code.
+ * Creates PhpGenerator representations from reflection objects or PHP source code.
  */
 final class Factory
 {
@@ -25,7 +25,11 @@ final class Factory
 	private array $extractorCache = [];
 
 
-	/** @param  \ReflectionClass<object>  $from */
+	/**
+	 * Creates a ClassLike instance from a reflection object.
+	 * @param  \ReflectionClass<object>  $from
+	 * @param  bool  $withBodies  load method bodies (requires nikic/php-parser, not available for anonymous/internal classes or interfaces)
+	 */
 	public function fromClassReflection(
 		\ReflectionClass $from,
 		bool $withBodies = false,
@@ -206,6 +210,10 @@ public function fromMethodReflection(\ReflectionMethod $from): Method
 	}
 
 
+	/**
+	 * Creates a GlobalFunction or Closure instance from a reflection object.
+	 * @param  bool  $withBody  load function body (requires nikic/php-parser, not available for closures or internal functions)
+	 */
 	public function fromFunctionReflection(\ReflectionFunction $from, bool $withBody = false): GlobalFunction|Closure
 	{
 		$function = $from->isClosure() ? new Closure : new GlobalFunction($from->name);
@@ -232,7 +240,10 @@ public function fromFunctionReflection(\ReflectionFunction $from, bool $withBody
 	}
 
 
-	/** @param callable(): mixed  $from */
+	/**
+	 * Creates a Method, GlobalFunction, or Closure instance from a callable.
+	 * @param  callable(): mixed  $from
+	 */
 	public function fromCallable(callable $from): Method|GlobalFunction|Closure
 	{
 		$ref = Nette\Utils\Callback::toReflection($from);
@@ -367,13 +378,20 @@ public function fromObject(object $obj): Literal
 	}
 
 
+	/**
+	 * Parses PHP source code and returns the first class-like type found.
+	 * @throws Nette\InvalidStateException if the code contains no class
+	 */
 	public function fromClassCode(string $code): ClassLike
 	{
 		$classes = $this->fromCode($code)->getClasses();
 		return reset($classes) ?: throw new Nette\InvalidStateException('The code does not contain any class.');
 	}
 
 
+	/**
+	 * Parses PHP source code and returns the resulting PhpFile representation.
+	 */
 	public function fromCode(string $code): PhpFile
 	{
 		$reader = new Extractor($code);

src/PhpGenerator/GlobalFunction.php

@@ -20,7 +20,11 @@ final class GlobalFunction
 	use Traits\CommentAware;
 	use Traits\AttributeAware;
 
-	/** @param string|(\Closure(): mixed)  $function */
+	/**
+	 * Creates an instance from a function name or closure reflection.
+	 * @param  string|(\Closure(): mixed)  $function
+	 * @param  bool  $withBody  load function body (requires nikic/php-parser)
+	 */
 	public static function from(string|\Closure $function, bool $withBody = false): self
 	{
 		return (new Factory)->fromFunctionReflection(Nette\Utils\Callback::toReflection($function), $withBody);

src/PhpGenerator/Helpers.php

@@ -138,6 +138,10 @@ public static function createObject(string $class, array $props): object
 	}
 
 
+	/**
+	 * Validates a type declaration. Strips the leading '?' and sets $nullable=true for nullable shorthand.
+	 * Returns null for empty/null types.
+	 */
 	public static function validateType(?string $type, bool &$nullable = false): ?string
 	{
 		if ($type === '' || $type === null) {

src/PhpGenerator/InterfaceType.php

@@ -40,6 +40,9 @@ public function getExtends(): array
 	}
 
 
+	/**
+	 * Adds a parent interface.
+	 */
 	public function addExtend(string $name): static
 	{
 		$this->validateNames([$name]);
@@ -49,7 +52,8 @@ public function addExtend(string $name): static
 
 
 	/**
-	 * Adds a member. If it already exists, throws an exception or overwrites it if $overwrite is true.
+	 * Adds a member to the interface.
+	 * @throws Nette\InvalidStateException if the member already exists and $overwrite is false
 	 */
 	public function addMember(Method|Constant|Property $member, bool $overwrite = false): static
 	{