Best practice comment header when extending IPS methods

[TSP]

Not that it really matters I guess...

But is there a considered "best practice" on the comment header for a method when extending/hooking it? 

1) Copy the original method header comment

2) Copy the original method header comment, and making any necessary clarifications/additions about what you do in the extension

3) Only have a comment telling what you do in the extension of the method. (No copying, so no @param , @return etc either). 

4) No comment

5) Dude, noone cares

 

Example of method I may extend and it's header comment:

	/**
	 * Hide/Delete All Content
	 *
	 * @param	string	$action	'hide' or 'delete' or 'merge'
	 * @param	array 	$extra	Extra data needed by the MemberContent plugin
	 * @return	void
	 */
	public function hideOrDeleteAllContent( $action, $extra=array() )

 

[bfarber]

I would say #5, followed by #2. Ultimately though, unless you are extending a REST API method (where the docblock header is used to automatically generate the REST API documentation in the AdminCP), no one except you and your clients would see it and/or care.

[TSP]

I'm extending $member->apiOutput in one case, I did find that I had to copy the entire header from the original Member class, in order for the response values to show up for REST API documentation in admin panel. 

[newbie LAC]

7 minutes ago, TSP said:

I'm extending $member->apiOutput in one case, I did find that I had to copy the entire header from the original Member class, in order for the response values to show up for REST API documentation in admin panel. 

Yes, it's a PITA. Next plugin comments will override previous.

I was going to create a topic.

IPS should add some {tags}