Jump to content

PHPDoc


Recommended Posts

I'm not quite sure where to post this, so I'm dumping it here.

Is it possible to please pay closer attention to the PHPDoc on methods? Particularly the return type. If the return type is not correct, it makes it really confusing in an IDE.

Example: From \IPS\Content\Search\Query

/**
 * Create new query
 *
 * @param	\IPS\Member	$member	The member performing the search (NULL for currently logged in member)
 * @return	\IPS\Content\Search
 */
public static function init( \IPS\Member $member = NULL )
{
	return new \IPS\Content\Search\Mysql\Query( $member ?: \IPS\Member::loggedIn() );
}

Return type there should be \IPS\Content\Search\Query, not \IPS\Content\Search.

Example: From \IPS\Content\Search\ContentFilter

/**
 * Constructor
 *
 * @param	string	$itemClass			The item class
 * @param	bool	$includeItems		Include items in results?
 * @param	bool	$includeComments	Include comments in results?
 * @param	bool	$includeReviews		Include reviews in results?
 * @return	\IPS\Content\Search\ContainerFilter
 */
public static function init( $itemClass, $includeItems=TRUE, $includeComments=TRUE, $includeReviews=TRUE )

This one is referencing a type that doesn't even exist. There is no ContainerFilter. It should be \IPS\Content\Search\ContentFilter or even just @return static.

Obviously I'm not asking everyone to go through all the methods now. But please pay attention, and if you happen to see one that's wrong, just fix it.

Thanks.

Side note: I have no idea how you guy survive without using an IDE. Just saying. I didn't say anything at all. Nope. Quiet as a mouse. 

Link to comment
Share on other sites

2 hours ago, CodingJungle said:

The Form has a similar one, it causes all sorts of squiggly in my IDE

I have reported that PHPdoc mistake quite some time ago via a support ticket. Someone ensured that it's fixed for upcoming releases :-). So maybe @HeadStand can report the remaining phpdoc mistakes via the support system too?

Link to comment
Share on other sites

4 hours ago, bfarber said:

We all fix them as we notice them. I'll fix the ones reported here, if you want to let me know of any others you are aware of I'll sort them too. :)

Thank you!

FWIW, the whole ContentFilter class uses ContainerFilter in the return type... the whole file needs  global replace.

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...