Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support reference in method tag #332

Merged
merged 1 commit into from
Apr 2, 2022
Merged

Support reference in method tag #332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 33 additions & 12 deletions src/DocBlock/Tags/Method.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,9 @@ final class Method extends BaseTag implements Factory\StaticMethod
/** @var Type */
private $returnType;

/** @var bool */
private $returnsReference;

/**
* @param array<int, array<string, Type|string>> $arguments
* @phpstan-param array<int, array{name: string, type: Type}|string> $arguments
Expand All @@ -66,19 +69,21 @@ public function __construct(
array $arguments = [],
?Type $returnType = null,
bool $static = false,
?Description $description = null
?Description $description = null,
bool $returnsReference = false
) {
Assert::stringNotEmpty($methodName);

if ($returnType === null) {
$returnType = new Void_();
}

$this->methodName = $methodName;
$this->arguments = $this->filterArguments($arguments);
$this->returnType = $returnType;
$this->isStatic = $static;
$this->description = $description;
$this->methodName = $methodName;
$this->arguments = $this->filterArguments($arguments);
$this->returnType = $returnType;
$this->isStatic = $static;
$this->description = $description;
$this->returnsReference = $returnsReference;
}

public static function create(
Expand All @@ -95,11 +100,13 @@ public static function create(
// 2. optionally the keyword "static" followed by whitespace
// 3. optionally a word with underscores followed by whitespace : as
// type for the return value
// 4. then optionally a word with underscores followed by () and
// 4. optionally an ampersand followed or not by whitespace : as
// a reference
// 5. then optionally a word with underscores followed by () and
// whitespace : as method name as used by phpDocumentor
// 5. then a word with underscores, followed by ( and any character
// 6. then a word with underscores, followed by ( and any character
// until a ) and whitespace : as method name with signature
// 6. any remaining text : as description
// 7. any remaining text : as description
if (
!preg_match(
'/^
Expand All @@ -122,6 +129,11 @@ public static function create(
)
\s+
)?
# Returns reference
(?:
(&)
\s*
)?
# Method name
([\w_]+)
# Arguments
Expand All @@ -139,14 +151,16 @@ public static function create(
return null;
}

[, $static, $returnType, $methodName, $argumentLines, $description] = $matches;
[, $static, $returnType, $returnsReference, $methodName, $argumentLines, $description] = $matches;

$static = $static === 'static';

if ($returnType === '') {
$returnType = 'void';
}

$returnsReference = $returnsReference === '&';

$returnType = $typeResolver->resolve($returnType, $context);
$description = $descriptionFactory->create($description, $context);

Expand All @@ -172,7 +186,7 @@ public static function create(
}
}

return new static($methodName, $arguments, $returnType, $static, $description);
return new static($methodName, $arguments, $returnType, $static, $description, $returnsReference);
}

/**
Expand Down Expand Up @@ -207,6 +221,11 @@ public function getReturnType(): Type
return $this->returnType;
}

public function returnsReference(): bool
{
return $this->returnsReference;
}

public function __toString(): string
{
$arguments = [];
Expand All @@ -228,9 +247,11 @@ public function __toString(): string

$methodName = $this->methodName;

$reference = $this->returnsReference ? '&' : '';

return $static
. ($returnType !== '' ? ($static !== '' ? ' ' : '') . $returnType : '')
. ($methodName !== '' ? ($static !== '' || $returnType !== '' ? ' ' : '') . $methodName : '')
. ($methodName !== '' ? ($static !== '' || $returnType !== '' ? ' ' : '') . $reference . $methodName : '')
. $argumentStr
. ($description !== '' ? ' ' . $description : '');
}
Expand Down
42 changes: 42 additions & 0 deletions tests/unit/DocBlock/Tags/MethodTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -339,6 +339,7 @@ public function testFactoryMethod(): void
$this->assertEquals($expectedArguments, $fixture->getArguments());
$this->assertInstanceOf(Void_::class, $fixture->getReturnType());
$this->assertSame($description, $fixture->getDescription());
$this->assertFalse($fixture->returnsReference());
}

/**
Expand Down Expand Up @@ -370,6 +371,7 @@ public function testReturnTypeThis(): void
$this->assertSame('static $this myMethod()', (string) $fixture);
$this->assertSame('myMethod', $fixture->getMethodName());
$this->assertInstanceOf(This::class, $fixture->getReturnType());
$this->assertFalse($fixture->returnsReference());
}

/**
Expand Down Expand Up @@ -401,6 +403,7 @@ public function testReturnTypeNoneWithLongMethodName(): void
$this->assertSame('void myVeryLongMethodName(mixed $node)', (string) $fixture);
$this->assertSame('myVeryLongMethodName', $fixture->getMethodName());
$this->assertInstanceOf(Void_::class, $fixture->getReturnType());
$this->assertFalse($fixture->returnsReference());
}

/**
Expand Down Expand Up @@ -542,6 +545,7 @@ public function testCreateMethodParenthesisMissing(): void
$this->assertEquals([], $fixture->getArguments());
$this->assertInstanceOf(Void_::class, $fixture->getReturnType());
$this->assertSame($description, $fixture->getDescription());
$this->assertFalse($fixture->returnsReference());
}

/**
Expand Down Expand Up @@ -578,6 +582,7 @@ public function testCreateMethodEmptyArguments(): void
$this->assertEquals([], $fixture->getArguments());
$this->assertInstanceOf(Void_::class, $fixture->getReturnType());
$this->assertSame($description, $fixture->getDescription());
$this->assertFalse($fixture->returnsReference());
}

/**
Expand Down Expand Up @@ -613,6 +618,7 @@ public function testCreateWithoutReturnType(): void
$this->assertEquals([], $fixture->getArguments());
$this->assertInstanceOf(Void_::class, $fixture->getReturnType());
$this->assertSame($description, $fixture->getDescription());
$this->assertFalse($fixture->returnsReference());
}

/**
Expand Down Expand Up @@ -656,4 +662,40 @@ public function testCreateWithMixedReturnTypes(): void
$fixture->getReturnType()
);
}

/**
* @uses \phpDocumentor\Reflection\DocBlock\Tags\Method::<public>
* @uses \phpDocumentor\Reflection\DocBlock\DescriptionFactory
* @uses \phpDocumentor\Reflection\TypeResolver
* @uses \phpDocumentor\Reflection\DocBlock\Description
* @uses \phpDocumentor\Reflection\Fqsen
* @uses \phpDocumentor\Reflection\Types\Context
* @uses \phpDocumentor\Reflection\Types\String_
*
* @covers ::create
*/
public function testCreateWithReference(): void
{
$descriptionFactory = m::mock(DescriptionFactory::class);
$resolver = new TypeResolver();
$context = new Context('');

$description = new Description('');

$descriptionFactory->shouldReceive('create')->with('', $context)->andReturn($description);

$fixture = Method::create(
'string &myMethod()',
$resolver,
$descriptionFactory,
$context
);

$this->assertSame('string &myMethod()', (string) $fixture);
$this->assertSame('myMethod', $fixture->getMethodName());
$this->assertEquals([], $fixture->getArguments());
$this->assertInstanceOf(String_::class, $fixture->getReturnType());
$this->assertSame($description, $fixture->getDescription());
$this->assertTrue($fixture->returnsReference());
}
}