Jump to content

Best practice comment header when extending IPS methods


TSP

Recommended Posts

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() )

 

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

  • 4 months later...
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}

Link to comment
Share on other sites

Archived

This topic is now archived and is closed to further replies.

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...