Conversation
| <refnamediv> | ||
| <refname>is_a</refname> | ||
| <refpurpose>Checks if the object is of this class or has this class as one of its parents</refpurpose> | ||
| <refpurpose>Checks if the object is of this class or has this class as one of its parents, or implements this interface</refpurpose> |
There was a problem hiding this comment.
I think the refpurpose is already too long; we should somehow shorten it. The additional mention of interfaces should go into the description section (first paragraph after the methodsynopsis), though.
| <refnamediv> | ||
| <refname>is_a</refname> | ||
| <refpurpose>Checks if the object is of this class or has this class as one of its parents</refpurpose> | ||
| <refpurpose>Checks if the object is of this class or has this class as one of its parents, or implements this interface</refpurpose> |
There was a problem hiding this comment.
How about?
| <refpurpose>Checks if the object is of this class or has this class as one of its parents, or implements this interface</refpurpose> | |
| <refpurpose>Checks if the object is an instance of a class/interface</refpurpose> |
There was a problem hiding this comment.
I thought about that as well, but the first parameter may be a class/interface name.
There was a problem hiding this comment.
| <refpurpose>Checks if the object is of this class or has this class as one of its parents, or implements this interface</refpurpose> | |
| <refpurpose>Checks if the object is a subtype of a class/interface</refpurpose> |
Maybe?
There was a problem hiding this comment.
I think "subtype" is worse than "instance of", since the former doesn't cover the case where the object is of that type. If in doubt, we should stick with "object" (for now), and change to "instance of". The description section could still clarify.
There was a problem hiding this comment.
Idea for description:
The function will return true if the object is either of that class,
a child of that class, or implement that interface.
| <refnamediv> | ||
| <refname>is_a</refname> | ||
| <refpurpose>Checks if the object is of this class or has this class as one of its parents</refpurpose> | ||
| <refpurpose>Checks if the object is of this class or has this class as one of its parents, or implements this interface</refpurpose> |
There was a problem hiding this comment.
Let me try something completely different to give us new ideas:
| <refpurpose>Checks if the object is of this class or has this class as one of its parents, or implements this interface</refpurpose> | |
| <refpurpose>Compares the object's type to a given class name</refpurpose> |
There was a problem hiding this comment.
Well, is_a() is a big mess. You can pass an object or a class/interface name as first argument (the former case should better be served by using instanceof), and there is even a third parameter which allows to prevent passing a class/interface name as first argument. How is one supposed to document that in a concise way?
There was a problem hiding this comment.
Assuming the refpurpose is about the purpose of the function, not the behavior, then we merely need to state why devs might want to use it. The exact behavior and all its exceptions can be detailed within the relevant parameters.
There was a problem hiding this comment.
Right, but talking about "the object" is misleading (especially since the function is mostly useful to compare class/interface names). Maybe something very general, like "Checks type relation", is appropriate as refpurpose?
There was a problem hiding this comment.
Some more ideas:
- Checks type correspondence
- Checks type analogy
- Compares types
By the way, subclass is a viable term in the context of interfaces as well. See first sentence of LSP: https://en.wikipedia.org/wiki/Liskov_substitution_principle
There was a problem hiding this comment.
"Subtype" might be preferable, though, but my actual with this term is that T is not a subtype/subclass of T. Isn't there are word which expresses "same type or subtype"?
There was a problem hiding this comment.
I can't think of such a word. Perhaps two words are still short enough: "Checks whether the object is of a given type or subtype"
There was a problem hiding this comment.
I'm still not happy with "object", but it's overall better than before, so maybe just go with that. :)
Co-authored-by: Anna Filina <afilina@gmail.com>
Co-authored-by: Anna Filina <afilina@gmail.com> Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de> Co-authored-by: George Peter Banyard <girgias@php.net>
No description provided.