The first line means a summary.(not a description)

I think this is designed behavior.

https://www.phpdoc.org/docs/latest/guides/inheritance.html#the-inheritdoc-tag

Thanks.

This behavior is impractical and IMO doesn't make any sense. If you place {@inheritdoc} on the top of the methods phpdoc, you're clearly want to inherit also method summary. Right now it is impossible to append additional description to the method without repeating the summary over and over (which contradicts the documentation inheritance concept).

IMO such code:

---

class A {

	/**
	 * Method A::test1() summary.
	 *
	 * Method A::test1() description.
	 */
	public static function test1() {
		
	}

	/**
	 * Method A::test2() summary.
	 */
	public static function test2() {
		
	}

}

class B extends A {

	/**
	 * {@inheritdoc}
	 * Additional B::test1() description.
	 */
	public static function test1() {
		
	}

	/**
	 * {@inheritdoc}
	 * Method B::test2() description.
	 */
	public static function test2() {
		
	}

}

class C extends A {

	/**
	 * Method C::test1() summary.	 
	 * {@inheritdoc}
	 * Additional C::test1() description.
	 */
	public static function test1() {
		
	}

	/**
	 * Method C::test2() summary.
	 * {@inheritdoc}
	 */
	public static function test2() {
		
	}

}

---

should be equivalent to:

---

class B extends A {

	/**
	 * Method A::test1() summary.
	 *
	 * Method A::test1() description.
	 * Additional B::test1() description.
	 */
	public static function test1() {
		// inherit summary and description
	}

	/**
	 * Method A::test2() summary.
	 *
	 * Method B::test2() description.
	 */
	public static function test2() {
		// inherit summary, no description to inherit
	}

}

class C extends A {

	/**
	 * Method C::test1() summary.
	 *  
	 * Method A::test1() description.
	 * Additional C::test1() description.
	 */
	public static function test1() {
		// override summary, inherit description
	}

	/**
	 * Method C::test2() summary.
	 */
	public static function test2() {
		// override summary, no description to inherit
	}

}

---

It is much more practical and consistent with phpdoc which contains only {@inheritdoc} tag.
AFAIK PhpStorm works in this way.

Perhaps, this can be improved a bit. 

<?php
class A {
    
    /**
     * TEST.
     */
    public function test() {
        
    }
}


class B extends A{
    /**
     * {@inheritdoc}
     * Desctiption.
     */
    public function test() {
        
    }
}

in this case, use the parent summary, then just add the child description.
i.e. 
    /**
     * TEST.
     * Desctiption.
     */

But in the following case, the parent description is overwritten.

class A {
    
    /**
     * TEST.
     * Description A.
     */
    public function test() {
        
    }
}


class B extends A{
    /**
     * {@inheritdoc}
     * Desctiption B.
     */
    public function test() {
        
    }
}

i.e.
    /**
     * TEST.
     * Description B.
     */

> But in the following case, the parent description is overwritten.

Why? Shouldn't this inherit both summary and description, and append new description to inherited one?

(In reply to rob006 from comment #4)
> > But in the following case, the parent description is overwritten.
> 
> Why? Shouldn't this inherit both summary and description, and append new
> description to inherited one?

It's the same behavior as phpDocumentor.

(In reply to junichi11 from comment #5)
> It's the same behavior as phpDocumentor.

phpDocumentor does not process {@inheritdoc} for summaries: https://i.rob006.net/18194626.png

For B::test1() it treats description as part of summary, and inherit description from A::test1(). The result is quite unexpected...

It would be great if you submit your proposal to phpDocumentor. If you know the proper documentation for @inheritdoc tag, please let us know. I'll look at it.

Thanks.

AFAIK there is no real standard for phpdoc, and phpDocumentor is not a standardization organization - it is only one of the tools for generating documentation and it should not be treated as a specification.

I've made some more tests and phpDocumentor works pretty close to my suggestion, but it handle inheritance independently for each element.

This:

---
	/**
	 * {@inheritdoc}
	 *
	 * Method C::test1() description.
	 */
---

means "inherit summary and use 'Method C::test1() description.' as description".

This: 

---
	/**
	 * Method C::test1() summary.
	 *
	 * {@inheritdoc}
	 */
---

means "use 'Method C::test1() summary.' as summary and inherit description.

This: 

---
	/**
	 * Method C::test1() summary.
	 */
---

suprisingly works the same as as previous example - 'Method C::test1() summary.' is summary, and description is inherited.

If you want inherit both summary and description, and append something to description, you must use:

---
	/**
	 * {@inheritdoc}
	 *
	 * {@inheritdoc}
	 * Additional description.
	 */
---

which looks weird and impractical. I've never seen such syntax in any project.


I also checked PhpStorm behavior, and it work like dumb copy-paste without separating summary and description: https://i.rob006.net/16841b2c.png


So, I still think that my suggestion from comment #2 is the best option, but even dumb copy-paste like PhpStorm does will be good enough.

As I wrote, you should submit your issue to phpDocumentor.

Implementing your behavior means that the IDE suggests incorrect behavior for phpDocumentor users at the moment. I don't think that it is good. (I think that we have to also consider other users.)

Thanks.

(In reply to junichi11 from comment #9)
> As I wrote, you should submit your issue to phpDocumentor.

I'm not using phpDocumentor. And I don't know any users of phpDocumentor.


> Implementing your behavior means that the IDE suggests incorrect behavior for phpDocumentor users at the moment.

As I said, phpDocumentor is only one of the many tools for generating documentation. For example https://github.com/FriendsOfPHP/Sami is not compatible with phpDocumentor, so using phpDocumentor-way will suggest incorrect behavior for Symfony and Laravel users.

And I guess that most of the users will adjust their phpdoc to the IDE they're using, and in that case we should pick PhpStorm behavior. 

But honestly, any of proposed solutions (mine, phpDocumentor or PhpStorm) is much better than the current behavior. So choose the one that is easiest to do. :)

(In reply to rob006 from comment #10)
> (In reply to junichi11 from comment #9)
> > As I wrote, you should submit your issue to phpDocumentor.
> 
> I'm not using phpDocumentor. And I don't know any users of phpDocumentor.

That is not a bad way at all even if you are not a phpDocumentor user :)
It is better to have the same behavior between tools if possible.