Read more specific object class names from function/method signature #1060

Open
cweiske opened this Issue Oct 7, 2013 · 6 comments

Comments

Projects
None yet
3 participants

cweiske commented Oct 7, 2013

Some class names are really long, e.g. Companyname_Project_Package_Extension_Model_Foo_List. Putting them in @param makes the docblock unreadable.

I suggest that it should be possible to simply use object as type in the docblock, and phpdoc reads real class name from the method/function signature:

/**
 * Does something
 *
 * @param object $bar A Bar object
 *
 * @return void
 */
function foo(Bar $bar)
{
}

phpdoc should show $bar to be of type Bar.

This should only happend when @param is of type object and the type in the method signature is a specific class name.

Contributor

boenrobot commented Oct 7, 2013

But if the class name is long, wouldn't that sort of kill the point? I mean, if you have

/**
 * Does something
 *
 * @param object $bar A Bar object
 *
 * @return void
 */
function foo(Companyname_Project_Package_Extension_Model_Foo_List $bar)
{
}

That's hardly more readable than simply

/**
 * Does something
 *
 * @param Companyname_Project_Package_Extension_Model_Foo_List $bar A Bar object
 *
 * @return void
 */
function foo(Companyname_Project_Package_Extension_Model_Foo_List $bar)
{
}

Plus, phpDocumentor already supports aliases in the docblocks (assuming your code is PHP 5.3+), so you can already do

use Companyname_Project_Package_Extension_Model_Foo_List as B;

/**
 * Does something
 *
 * @param B $bar A Bar object
 *
 * @return void
 */
function foo(B $bar)
{
}

cweiske commented Oct 7, 2013

You have far more space to write a better description for the $bar parameter. Especially when sticking to 80 lines, you often only have space for one word:

/**
 * Does something
 *
 * @param Companyname_Project_Package_Extension_Model_Foo_List $bar Previously
 *                                                                  aquired bar
 *                                                                  object from
 *                                                                  outer space
 *
 * @return void
 */
function foo(Companyname_Project_Package_Extension_Model_Foo_List $bar)
{
}
Contributor

boenrobot commented Oct 7, 2013

But that's what aliases and namespaces were created for - to shorten names while still avoiding conflicts. Combine that with the fact that PHP 5.2 is now long past its EOL, and it's clear implementing some sort of primitive pseudo aliasing (i.e. aliasing "object" to "whatever the type hint says") is more trouble for its worth. I'd personally much prefer that to be an error in the report due to a mismatch between hint and declaration... I'm not sure if it is already one though.

cweiske commented Oct 7, 2013

Your solution (using namespaces) cannot be applied to large legacy codebases, only to new code.

Contributor

boenrobot commented Oct 7, 2013

That's a kind of a moot point - you'd need to modify said legacy codebases whatever the proposed solution is, though I see your point in that with your proposed solution, you could do that without the code itself breaking with an old PHP runtime.

How about instead we allow the type being omitted altogether, and use the type from the type hint THEN? In case there's no matching type hint either, phpDocumentor would still report an error for an undocumented type. I'm not sure if that's already working, but it's IMHO a better course of action to do it if not.

(and yes, I'm aware PEAR CS doesn't allow this, but it can be modified to allow it when a type hint is present)

The point is to preserve the current semantics of "object" as a generic "any object" indicator, rather than "an object - look at the hint for details".

Owner

mvriel commented Oct 9, 2013

I can understand the pain that @cweiske is talking about, in the past I have had issues with longer object names as well and still trying to limit the maximum line length.

Although I agree with @boenrobot that using an alias would be a more elegant way I can imagine that using object as a backup is an interesting instrument. In my opinion this would not change the meaning of object but rather indicate, rightly so, that the code is more specific and thus accurate.

So in short; I am not opposed to this feature. I do think that unless contributed that it will not be implemented soon as other issues take precedence

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment