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

Jump to bottom

Inherit method documentation through multiple generations #3701

Merged
merged 1 commit into from
May 8, 2024
Merged

Inherit method documentation through multiple generations #3701

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.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
108 changes: 71 additions & 37 deletions src/phpDocumentor/Descriptor/MethodDescriptor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,47 +210,23 @@ public function getInheritedElement(): MethodInterface|null
return $this->inheritedElement;
}

/** @var ClassInterface|InterfaceInterface|null $associatedClass */
$associatedClass = $this->getParent();
if (! $associatedClass instanceof ClassInterface && ! $associatedClass instanceof InterfaceInterface) {
return null;
}

$parentClass = $associatedClass->getParent();
if ($parentClass instanceof ClassInterface || $parentClass instanceof Collection) {
// the parent of a class is always a class, but the parent of an interface is a collection of interfaces.
$parents = $parentClass instanceof ClassInterface ? [$parentClass] :
$parentClass->filter(InterfaceInterface::class);
foreach ($parents as $parent) {
/** @var MethodInterface|null $parentMethod */
$parentMethod = $parent->getMethods()->fetch($this->getName());
if ($parentMethod instanceof self) {
$this->inheritedElement = $parentMethod;

return $this->inheritedElement;
}
/** @var ClassInterface|InterfaceInterface|null $methodParent */
$methodParent = $this->getParent();
if ($methodParent instanceof ClassInterface) {
/** @var MethodInterface|null $parentClassMethod */
$parentClassMethod = $this->recurseClassInheritance($methodParent);
if ($parentClassMethod instanceof self) {
$this->inheritedElement = $parentClassMethod;
}
}

// also check all implemented interfaces next if the parent is a class and not an interface
if ($associatedClass instanceof ClassInterface) {
/** @var InterfaceInterface|Fqsen $interface */
foreach ($associatedClass->getInterfaces() as $interface) {
if ($interface instanceof Fqsen) {
continue;
}

/** @var ?MethodInterface $parentMethod */
$parentMethod = $interface->getMethods()->fetch($this->getName());
if ($parentMethod instanceof self) {
$this->inheritedElement = $parentMethod;

return $this->inheritedElement;
}
} elseif ($methodParent instanceof InterfaceInterface) {
/** @var MethodInterface|null $parentInterfaceMethod */
$parentInterfaceMethod = $this->recurseInterfaceInheritance($methodParent);
if ($parentInterfaceMethod instanceof self) {
$this->inheritedElement = $parentInterfaceMethod;
}
}

return null;
return $this->inheritedElement;
}

/**
Expand All @@ -270,4 +246,62 @@ public function getHasReturnByReference(): bool
{
return $this->hasReturnByReference;
}

private function recurseClassInheritance(ClassInterface $currentClass): MethodInterface|null
{
/** @var ClassInterface|null $parentClass */
$parentClass = $currentClass->getParent();
if ($parentClass instanceof ClassInterface) {
/** @var MethodInterface|null $parentClassMethod */
$parentClassMethod = $parentClass->getMethods()->fetch($this->getName());
if ($parentClassMethod instanceof self) {
return $parentClassMethod;
}

/** @var MethodInterface|null $ancestorMethod */
$ancestorMethod = $this->recurseClassInheritance($parentClass);
if ($ancestorMethod instanceof self) {
return $ancestorMethod;
}
}

/** @var Collection<InterfaceInterface>|null $parentInterfaces */
$parentInterfaces = $currentClass->getInterfaces()->filter(InterfaceInterface::class);
foreach ($parentInterfaces as $parentInterface) {
/** @var MethodInterface|null $parentInterfaceMethod */
$parentInterfaceMethod = $parentInterface->getMethods()->fetch($this->getName());
if ($parentInterfaceMethod instanceof self) {
return $parentInterfaceMethod;
}

/** @var MethodInterface|null $ancestorMethod */
$ancestorMethod = $this->recurseInterfaceInheritance($parentInterface);
if ($ancestorMethod instanceof self) {
return $ancestorMethod;
}
}

return null;
}

private function recurseInterfaceInheritance(InterfaceInterface $currentInterface): MethodInterface|null
{
/** @var Collection<InterfaceInterface>|null $parentInterfaces */
$parentInterfaces = $currentInterface->getParent()->filter(InterfaceInterface::class);
foreach ($parentInterfaces as $parentInterface) {
/** @var MethodInterface|null $parentInterfaceMethod */
$parentInterfaceMethod = $parentInterface->getMethods()->fetch($this->getName());
if ($parentInterfaceMethod instanceof self) {
return $parentInterfaceMethod;
}

/** @var MethodInterface|null $ancestorMethod */
$ancestorMethod = $this->recurseInterfaceInheritance($parentInterface);
if ($ancestorMethod instanceof self) {
return $ancestorMethod;
}
}

return null;
}
}
150 changes: 150 additions & 0 deletions tests/unit/phpDocumentor/Descriptor/MethodDescriptorTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,156 @@ public function testParamTagsInheritWhenNoneArePresent(): void
$this->assertSame($paramCollection, $result);
}

public function testElementDoesNotInheritWhenNoParents(): void
{
$this->assertNull($this->fixture->getInheritedElement());

$associatedClass = new ClassDescriptor();
$associatedClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\Class'));
$this->fixture->setName('myMethod');
$this->fixture->setParent($associatedClass);

$this->assertNull($this->fixture->getInheritedElement());
}

public function testElementInheritanceCaches(): void
{
$parentClass = new ClassDescriptor();
$parentClass->setAbstract(true);
$parentClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\AbstractClass'));
$parentMethod = new MethodDescriptor();
$parentMethod->setName('myMethod');
$parentMethod->setParent($parentClass);
$parentClass->getMethods()->set($parentMethod->getName(), $parentMethod);

$associatedClass = new ClassDescriptor();
$associatedClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\Class'));
$associatedClass->setParent($parentClass);
$this->fixture->setName('myMethod');
$this->fixture->setParent($associatedClass);
$associatedClass->getMethods()->set($this->fixture->getName(), $this->fixture);

$this->fixture->getInheritedElement();
$this->assertSame($parentMethod, $this->fixture->getInheritedElement());
}

public function testElementInheritsWhenExtending(): void
{
$parentClass = new ClassDescriptor();
$parentClass->setAbstract(true);
$parentClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\AbstractClass'));
$parentMethod = new MethodDescriptor();
$parentMethod->setName('myMethod');
$parentMethod->setParent($parentClass);
$parentClass->getMethods()->set($parentMethod->getName(), $parentMethod);

$associatedClass = new ClassDescriptor();
$associatedClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\Class'));
$associatedClass->setParent($parentClass);
$this->fixture->setName('myMethod');
$this->fixture->setParent($associatedClass);
$associatedClass->getMethods()->set($this->fixture->getName(), $this->fixture);

$this->assertSame($parentMethod, $this->fixture->getInheritedElement());
}

public function testElementInheritsRecursivelyWhenExtending(): void
{
$parentClass1 = new ClassDescriptor();
$parentClass1->setAbstract(true);
$parentClass1->setFullyQualifiedStructuralElementName(new Fqsen('\My\AbstractClass1'));
$parentMethod1 = new MethodDescriptor();
$parentMethod1->setName('myMethod');
$parentMethod1->setParent($parentClass1);
$parentClass1->getMethods()->set($parentMethod1->getName(), $parentMethod1);

$parentClass2 = new ClassDescriptor();
$parentClass2->setAbstract(true);
$parentClass2->setFullyQualifiedStructuralElementName(new Fqsen('\My\AbstractClass2'));
$parentClass2->setParent($parentClass1);

$associatedClass = new ClassDescriptor();
$associatedClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\Class'));
$associatedClass->setParent($parentClass2);
$this->fixture->setName('myMethod');
$this->fixture->setParent($associatedClass);
$associatedClass->getMethods()->set($this->fixture->getName(), $this->fixture);

$this->assertSame($parentMethod1, $this->fixture->getInheritedElement());
}

public function testElementInheritsWhenImplementing(): void
{
$interface1 = new InterfaceDescriptor();
$interface1->setFullyQualifiedStructuralElementName(new Fqsen('\My\Interface1'));

$interface2 = new InterfaceDescriptor();
$interface2->setFullyQualifiedStructuralElementName(new Fqsen('\My\Interface2'));
$interface2->setParent(new Collection([$interface1]));
$interfaceMethod2 = new MethodDescriptor();
$interfaceMethod2->setName('myMethod');
$interface2->setMethods(new Collection([$interfaceMethod2]));
$interface2->getMethods()->set($interfaceMethod2->getName(), $interfaceMethod2);

$associatedClass = new ClassDescriptor();
$associatedClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\Class'));
$associatedClass->setInterfaces(new Collection([$interface1, $interface2]));
$this->fixture->setName('myMethod');
$this->fixture->setParent($associatedClass);
$associatedClass->getMethods()->set($this->fixture->getName(), $this->fixture);

$this->assertSame($interfaceMethod2, $this->fixture->getInheritedElement());
}

public function testElementInheritsRecursivelyWhenImplementing(): void
{
$interface1 = new InterfaceDescriptor();
$interface1->setFullyQualifiedStructuralElementName(new Fqsen('\My\Interface1'));
$interfaceMethod1 = new MethodDescriptor();
$interfaceMethod1->setName('myMethod');
$interfaceMethod1->setParent($interface1);
$interface1->setMethods(new Collection([$interfaceMethod1]));
$interface1->getMethods()->set($interfaceMethod1->getName(), $interfaceMethod1);

$interface2 = new InterfaceDescriptor();
$interface2->setFullyQualifiedStructuralElementName(new Fqsen('\My\Interface2'));
$interface2->setParent(new Collection([$interface1]));

$associatedClass = new ClassDescriptor();
$associatedClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\Class'));
$associatedClass->setInterfaces(new Collection([$interface2]));
$this->fixture->setName('myMethod');
$this->fixture->setParent($associatedClass);
$associatedClass->getMethods()->set($this->fixture->getName(), $this->fixture);

$this->assertSame($interfaceMethod1, $this->fixture->getInheritedElement());
}

public function testElementInheritsRecursivelyWhenExtendingAndImplementing(): void
{
$interface = new InterfaceDescriptor();
$interface->setFullyQualifiedStructuralElementName(new Fqsen('\My\Interface'));
$interfaceMethod = new MethodDescriptor();
$interfaceMethod->setName('myMethod');
$interfaceMethod->setParent($interface);
$interface->setMethods(new Collection([$interfaceMethod]));
$interface->getMethods()->set($interfaceMethod->getName(), $interfaceMethod);

$parentClass = new ClassDescriptor();
$parentClass->setAbstract(true);
$parentClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\AbstractClass'));
$parentClass->setInterfaces(new Collection([$interface]));

$associatedClass = new ClassDescriptor();
$associatedClass->setFullyQualifiedStructuralElementName(new Fqsen('\My\Class'));
$associatedClass->setParent($parentClass);
$this->fixture->setName('myMethod');
$this->fixture->setParent($associatedClass);
$associatedClass->getMethods()->set($this->fixture->getName(), $this->fixture);

$this->assertSame($interfaceMethod, $this->fixture->getInheritedElement());
}

/** @covers \phpDocumentor\Descriptor\DescriptorAbstract::getAuthor */
public function testAuthorTagsInheritWhenNoneArePresent(): void
{
Expand Down