PHPDoc enhancement: @alias/@aliasof

[Ryan Parman]

I would like to propose the following enhancement to be included in a future PHPDoc-specific PSR: @alias (or @aliasof).

@alias

The @alias tag is used to document methods which are nothing more than aliases of other methods.

## Syntax

@alias [method]

## Description

The @alias tag can be used to indicate another method that the current method acts as an alias to. References to other classes are syntactically similar to the @see tag, and behave in a way that is essentially the opposite of {@inheritdoc}. Instead of pulling the DocBlock content from the outside method into the current one, the current method is instead added to an "aliases" trait (lowercase "t") on the outside method.

In this manner, aliases never receive a method entry of their own, but instead are listed as aliases in the documentation for the outside method.

## Examples

Method in the current class:

/**

 * @alias method()

 */

----

Method in another class. This includes namespaced classes (`\Vendor\Package\Class`), as well as class names that use namespace resolution (`use Vendor\Package\Class;` "`Class`").

/**

 * @alias Class::method()

 */

----

(In human-consumable documentation:)

Method: `putObject()` (aliased as: `createObject()`)

...

[Paul Dragoonis]

Hi Ryan,

I'm not opposing your idea but I'm pointing out that I use @see for
this purpose.

i.e: @see $this:otherMethod
or: @see ClassName::otherMethod

- Paul.

> --
> You received this message because you are subscribed to the Google Groups
> "PHP Framework Interoperability Group" group.
> To post to this group, send email to php...@googlegroups.com.
> To unsubscribe from this group, send email to
> php-fig+u...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Marco Pivetta]

Shouldn't this (usually) be handled via @deprecated <please describe why you should use the other method> ? (and then what Paul said)

Marco Pivetta

http://twitter.com/Ocramius     

http://marco-pivetta.com    

[Sebastian Krebs]

@deprecated and @alias is something different, at least because an aliased method shouldn't disappear (as long as it's not deprecated too).

    function stringStartsWith ($subject, $string) { /* code */ }

    /**

     * @alias stringStartsWith

     */

    function prefixOf ($subject, $prefix) { /* code */ }

Depending on the context (handling prefixes, or just any kind of strings) both methods makes sense, because they give an additional semantical meaning to the completely same behaviour. I wouldn't deprecate any of both and marking one as "X behaves exactly like Y" seems legit.

2012/10/9 Marco Pivetta <ocra...@gmail.com>

--
github.com/KingCrunch

[Mike van Riel]

I have been thinking about this proposal for quite some time but do
not see the added value of `@alias` over `@see`.
I try to keep the amount of tags to a minimum to prevent feature bloat
and to enable users to remember all tags (which becomes troublesome if
there are too many). Adding a new tag @alias over @see does not seem
to be inline with that goal.

@Ryan: can you please elaborate on the exact difference between @see
and @alias; why do you think they should be 2 different tags?

[Marco Pivetta]

@sebastian yes, what I mean is that the use case is a niche often covered by @see, and more often caused by rename and subsequent deprecation

[Ryan Parman]

@see is often used when one method needs to be able to _reference_ another method -- such as when they're related to each other. (This was precisely why I didn't propose a @related tag as well.)

@alias would be used when one method is _identical_ to another in every way. It is, quite literally, an alias.

See: http://php.net/join and http://php.net/implode

[Sebastian Krebs]

2012/10/9 Ryan Parman <ry...@ryanparman.com>

@see is often used when one method needs to be able to _reference_ another method -- such as when they're related to each other. (This was precisely why I didn't propose a @related tag as well.)

@alias would be used when one method is _identical_ to another in every way. It is, quite literally, an alias.

Which is a reference in some form too ;) I think @see is the superset of @alias, @related (and so on) means: @see is a loose reference with no deeper meaning (just "You may have a look at X"), whereas @alias is a reference with a semantic meaning (namely "You may have a look at X, because I'm an alias of it"). I don't think there is anything wrong with

@see implode() Alias

--
github.com/KingCrunch

[Johannes Schmitt]

The advantage of more specific annotations is that they can be better handled by automated tools/IDEs.

I'm not sure if this is warranted in this specific case, though I wonder what the permissible contents for the @see tag are. I've always used this in connection with links so far.

Johannes

[Ryan Parman]

Continuing to rely on @see has two immediate problems that I can see.

1. It continues to enforce a lowest-common-denominator approach. The lack of granularity prevents documentation tool developers from enhancing the end-user experience in this area. From a UX and user research perspective, you want to reduce as much cognitive load for a user as possible. If a user is looking for related methods/classes and clicks a link _expecting_ to see new information about a new method/class, then we've met the users expectations. But if we were able to avoid having yet-another-method-entry in the docs and/or show multiple names for a method in the same spot at the same time, we can further reduce the cognitive load that is required for a user to mentally parse the documentation.

2. While it would be up to documentation tool developers to choose how to display the results of this annotation, I would prefer NOT to have @alias be the equivalent of:

/**
* {@inheritdoc Class::method()}
* @see Class::method()
*/

My preference would be to remove the method with the @alias tag all-together, and instead add the aliased method to the documentation tool's metadata of the aliasee (if that's even a real word). At present, there's no way to annotate that in the DocBlock.

I agree with what Johannes said: "The advantage of more specific annotations is that they can be better handled by automated tools/IDEs" (and documentation generators).

> On Tue, Oct 9, 2012 at 12:39 PM, Sebastian Krebs <kreb...@gmail.com> wrote:
>>
>> function stringStartsWith ($subject, $string) { /* code */ }
>>
>> /**
>> * @alias stringStartsWith
>> */
>> function prefixOf ($subject, $prefix) { /* code */ }

This is precisely what I'm suggesting.

> On Tue, Oct 9, 2012 at 5:04 PM, Sebastian Krebs <kreb...@gmail.com> wrote:
>>

>> @see implode() Alias

I'm not opposed to this either, although my preference is for the cleaner (IMO) @alias tag. More importantly, however, is that I'd like to see something codified before I go off and implement my own thing.

On Oct 9, 2012, at 8:35 AM, Johannes Schmitt <schmi...@gmail.com> wrote:

> The advantage of more specific annotations is that they can be better handled by automated tools/IDEs.
>
> I'm not sure if this is warranted in this specific case, though I wonder what the permissible contents for the @see tag are. I've always used this in connection with links so far.
>
> Johannes
>
> On Tue, Oct 9, 2012 at 5:04 PM, Sebastian Krebs <kreb...@gmail.com> wrote:
>
>
> 2012/10/9 Ryan Parman <ry...@ryanparman.com>
> @see is often used when one method needs to be able to _reference_ another method -- such as when they're related to each other. (This was precisely why I didn't propose a @related tag as well.)
>
> @alias would be used when one method is _identical_ to another in every way. It is, quite literally, an alias.
>
> Which is a reference in some form too ;) I think @see is the superset of @alias, @related (and so on) means: @see is a loose reference with no deeper meaning (just "You may have a look at X"), whereas @alias is a reference with a semantic meaning (namely "You may have a look at X, because I'm an alias of it"). I don't think there is anything wrong with
>
> @see implode() Alias
>
>
> See: http://php.net/join and http://php.net/implode
>
>
>
> On Oct 9, 2012, at 3:54 AM, Mike van Riel <draco...@gmail.com> wrote:
>
> > I have been thinking about this proposal for quite some time but do
> > not see the added value of `@alias` over `@see`.
> > I try to keep the amount of tags to a minimum to prevent feature bloat
> > and to enable users to remember all tags (which becomes troublesome if
> > there are too many). Adding a new tag @alias over @see does not seem
> > to be inline with that goal.
> >
> > @Ryan: can you please elaborate on the exact difference between @see
> > and @alias; why do you think they should be 2 different tags?
> >

[Ryan Parman]

An updated, clearer proposal for @alias.

https://github.com/skyzyx/vanity/wiki/PHPDoc-Extension:-@alias

[Mike van Riel]

I can understand that from a documentation generator point of view it
could help to be able to generate reports, show a distinct icon and
such. But from a code author point of view I think this tag might not
be a snug fit.

@alias would be a specialization of @see, to identify a single
purpose. There are other types of relations that can be expressed, is
it wise to introduce a new tag for each of those? I see in the field
that people have trouble distinguishing between @link and @see; why
would this be any different for @alias? Especially given how often you
would use such a tag (imo: seldom if you write proper code and do not
have to maintain a huge BC).

Something that might be more interesting is to see if we can alter
@see in such a way that you are able to optionally add a 'type' of
relation. This way you could model it without making it overly complex
for the code author (and it might even be possible to deprecate @uses
and @link).

[Chuck Burgess]

On Thursday, October 11, 2012 1:46:06 AM UTC-5, Mike van Riel wrote: 

Something that might be more interesting is to see if we can alter
@see in such a way that you are able to optionally add a 'type' of
relation. This way you could model it without making it overly complex
for the code author (and it might even be possible to deprecate @uses
and @link).

This is an intriguing idea, particularly given the potential scope of deprecating those other two tags.
CRB

[Ryan Parman]

Okay, I'll bite. What did you have in mind?

Although I disagree with deprecating @link in favor of @see. According to the (hard to find and hard to parse) phpDocumentor 1.x manual, @see is for linking to other structural elements of the code (classes, methods, properties, etc.), while @link is for, well, links. Proper URLs.

But I'm willing to be convinced if a compelling idea is proposed.

[Ryan Parman]

On Oct 10, 2012, at 11:45 PM, Mike van Riel <draco...@gmail.com> wrote:

> @alias would be a specialization of @see, to identify a single
> purpose. There are other types of relations that can be expressed, is
> it wise to introduce a new tag for each of those?

What do you actually see being used in the real world? Concrete examples would be helpful. :)

> I see in the field
> that people have trouble distinguishing between @link and @see; why
> would this be any different for @alias?

Arguably, that has nothing to do with the tags, and more to do with the absolute mess of a site phpDocumentor 1.x has. If people can't *find* the documentation, they can't *use* the documentation.

> Especially given how often you
> would use such a tag (imo: seldom if you write proper code and do not
> have to maintain a huge BC).

IMO, it depends on what you're doing. For example, say you're implementing some kind of collection and you want a method that returns true if all of the entries match a particular pattern.

Would you call that method every() or all()?

The truth is, you can call it both by aliasing one to the other. Some users will remember all() while others will remember every(). When we document them, we can simply say "these are the same". The @alias annotation makes that easier.

[Sebastian Krebs]

2012/10/11 Ryan Parman <ry...@ryanparman.com>

On Oct 10, 2012, at 11:45 PM, Mike van Riel <draco...@gmail.com> wrote:

> @alias would be a specialization of @see, to identify a single
> purpose. There are other types of relations that can be expressed, is
> it wise to introduce a new tag for each of those?

What do you actually see being used in the real world? Concrete examples would be helpful. :)

> I see in the field
> that people have trouble distinguishing between @link and @see; why
> would this be any different for @alias?

Arguably, that has nothing to do with the tags, and more to do with the absolute mess of a site phpDocumentor 1.x has. If people can't *find* the documentation, they can't *use* the documentation.

> Especially given how often you
> would use such a tag (imo: seldom if you write proper code and do not
> have to maintain a huge BC).

IMO, it depends on what you're doing. For example, say you're implementing some kind of collection and you want a method that returns true if all of the entries match a particular pattern.

Would you call that method every() or all()?

Regarding the fact, that a method/function name should include an activity (--> verb) I would call it "matchAll()", thus "matchEvery()" sounds silly.

However, do you really implement a method multiple times just because a developer cannot remember a (max) 5 characters method name? My argument earlier was, that it makes sense to create alias methods/functions, if both identifiers represent a different meaning (like "top()" in a stack and "front()"/"first()" in a queue), but in your example they are semantically identical. This makes me think you assume, that your users wont read the API-doc, so why want to document the aliased-nature of both within the API-doc? And when they can't remember the methods, why should they even want to know, that a method is an alias of another one?

Really: Your example is really no valid case for useful alias. There is absolutely no reason to habe both methods, except "some will remember x() better than y()" ...

 

The truth is, you can call it both by aliasing one to the other. Some users will remember all() while others will remember every(). When we document them, we can simply say "these are the same". The @alias annotation makes that easier.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[justin]

On Thu, Oct 11, 2012 at 11:20 AM, Sebastian Krebs <kreb...@gmail.com> wrote:
> Really: Your example is really no valid case for useful alias. There is
> absolutely no reason to habe both methods, except "some will remember x()
> better than y()" ...

I disagree. There are lots of great reasons for aliases. You just
found one example that you disagreed with :)

Aliases are almost essential when implementing standard interfaces...

Take ArrayAccess: offsetExists() is almost always an alias for has(),
offsetGet() is almost always an alias for get() or find(). If the same
class implements property overloading as well, __get(), __set(),
__isset() and __unset() will be aliases too.

Classes using PSR-[23] naming conventions which implement a stream
wrapper should probably alias all the non-camelcase methods to proper
PSR-[23] method names.

A template class might implement __invoke() as an alias to render().
And by "might" I mean "at least one definitely does":
http://hile.mn/RjgFvm

Aliases can also provide a more expressive interface, especially with
DSLs and fluent interfaces.

-- j

[Mike van Riel]

See my comments in the following reply text

On Thu, Oct 11, 2012 at 7:03 PM, Ryan Parman <ry...@ryanparman.com> wrote:
> On Oct 10, 2012, at 11:45 PM, Mike van Riel <draco...@gmail.com> wrote:
>
>> @alias would be a specialization of @see, to identify a single
>> purpose. There are other types of relations that can be expressed, is
>> it wise to introduce a new tag for each of those?
>
> What do you actually see being used in the real world? Concrete examples would be helpful. :)

http://www.iana.org/assignments/link-relations/link-relations.xml

>> I see in the field
>> that people have trouble distinguishing between @link and @see; why
>> would this be any different for @alias?
>
> Arguably, that has nothing to do with the tags, and more to do with the absolute mess of a site phpDocumentor 1.x has. If people can't *find* the documentation, they can't *use* the documentation.

This argument is your subjective opinion and serves no basis for a
counter argument: http://lmgtfy.com/?q=phpdoc+tags
The sidebar shown in the first link shows a clear summary of which
tags there are; still @link and @see get confused regularly.

>> Especially given how often you
>> would use such a tag (imo: seldom if you write proper code and do not
>> have to maintain a huge BC).
>
> IMO, it depends on what you're doing. For example, say you're implementing some kind of collection and you want a method that returns true if all of the entries match a particular pattern.
>
> Would you call that method every() or all()?
>
> The truth is, you can call it both by aliasing one to the other. Some users will remember all() while others will remember every(). When we document them, we can simply say "these are the same". The @alias annotation makes that easier.

This specific example is not one that I would use in real life but I
concede to some of the examples in later posts.

[Mike van Riel]

On Thu, Oct 11, 2012 at 9:45 PM, justin <jus...@justinhileman.info> wrote:
> On Thu, Oct 11, 2012 at 11:20 AM, Sebastian Krebs <kreb...@gmail.com> wrote:
>> Really: Your example is really no valid case for useful alias. There is
>> absolutely no reason to habe both methods, except "some will remember x()
>> better than y()" ...
>
> I disagree. There are lots of great reasons for aliases. You just
> found one example that you disagreed with :)
>
> Aliases are almost essential when implementing standard interfaces...
>
> Take ArrayAccess: offsetExists() is almost always an alias for has(),
> offsetGet() is almost always an alias for get() or find(). If the same
> class implements property overloading as well, __get(), __set(),
> __isset() and __unset() will be aliases too.

I have to disagree with this example. I personally have not seen the
aliassing of any of the above as the magic methods automatically map
to language constructs. For example:
http://php.net/manual/en/class.arrayobject.php
Same goes for __get() and __set(); what would you want to alias?

> Classes using PSR-[23] naming conventions which implement a stream
> wrapper should probably alias all the non-camelcase methods to proper
> PSR-[23] method names.

That might be the case; although PSR-1 and PSR-2 do not force you to
change the way pre-existing classes (expecially PHP classes) are. But
I can see that happening.

> A template class might implement __invoke() as an alias to render().
> And by "might" I mean "at least one definitely does":
> http://hile.mn/RjgFvm

I can relate to that one; just as __toString() often is an alias of
getName() or getLabel() or such a method.

> Aliases can also provide a more expressive interface, especially with
> DSLs and fluent interfaces.

I agree with this example.

But I'd like to cut this short; whether aliases are useful or not is
not the question. The question is: how useful is a specialization of
@see as a separate new tag?

I reiterate what I said earlier; I believe it would be more useful to
look for a good way to change the @see tag and broaden its
applicability.
Why? Quite simple: there are more relation types such as 'inherits
from', 'extends', 'uses', 'manual' (for a link to the reference
documentation), 'wraps', to name few I can imagine on the top of my
head! Are these use-cases for their own tag as well? (where uses is a
cute example since it is its own tag!)
Also: what will happen if in 1 or 2 years someone comes along with a
new strong case for a tag representing a relation type; are we going
to write a new Core PSR to add the tag? An extension?

As far as I am concerned the @see tag can be repurposed to make it
open for future reuse (open/closed principle?).

The notation is something which we can debate on; I was hoping someone
else would have kicked off the discussion but I'll start with a
suggestion then.

Example:

`@see my_method() :alias: to provide a method that matches the Coding Standard`

2nd example:

`@see http://manual.phpdoc.org :manual: to provide details regarding
the use of phpDocumentor v1`

[Sebastian Krebs]

2012/10/11 justin <jus...@justinhileman.info>

On Thu, Oct 11, 2012 at 11:20 AM, Sebastian Krebs <kreb...@gmail.com> wrote:
> Really: Your example is really no valid case for useful alias. There is
> absolutely no reason to habe both methods, except "some will remember x()
> better than y()" ...

I disagree. There are lots of great reasons for aliases. You just
found one example that you disagreed with :)

I know, that there are valid examples for alias-methods, I even gave some myself, and you are right, that I found an example, that I disagree with. You don't?

_Duplicated_ methods are useless and just clutter the class with methods and the documentation with unneeded stuff about which methods all behave the same like which other methods. Keep your interface [1] small. And yes, there is a difference between two methods, that are just duplicates, or two methods, that only behaves identical, but serve a different purpose in their context (like the mentioned "top()" (stack) and "first()" (queue)).

[1] Remember, that by definition an interface means the sum of all accessable methods and properties of a class too. The implemented interface is (more or less) just a formal description bound to a type (the interface name).

 

Aliases are almost essential when implementing standard interfaces...

Take ArrayAccess: offsetExists() is almost always an alias for has(),
offsetGet() is almost always an alias for get() or find(). If the same
class implements property overloading as well, __get(), __set(),
__isset() and __unset() will be aliases too.

Beside: "has()" (test, wether a value is within a set of values) and "offsetExists()" (Test, wether a key exists) are _not_ the same, nor equivalent (or similar). Same with "offsetGet()" and "find()". "has()" and "contains()" would be kind of alias methods, but again I see no reason to implement both ^^ (for now. Didn't thought much about them)

However: _Decide_ which interface you want to provide to the user and don't let it grow as much as possible with every kind of known access method, just because "some like A more and some B". At the end it's more confusing, then helpful. And it's still not a really good argument for @alias.

 

Classes using PSR-[23] naming conventions which implement a stream
wrapper should probably alias all the non-camelcase methods to proper
PSR-[23] method names.

A template class might implement __invoke() as an alias to render().
And by "might" I mean "at least one definitely does":
http://hile.mn/RjgFvm

Aliases can also provide a more expressive interface, especially with
DSLs and fluent interfaces.

-- j

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[Sebastian Krebs]

2012/10/11 Mike van Riel <draco...@gmail.com>

Started a mail earlier. Got lost somewhere. Don't know where ....

 

Example:

`@see my_method() :alias: to provide a method that matches the Coding Standard`

2nd example:

`@see http://manual.phpdoc.org :manual: to provide details regarding
the use of phpDocumentor v1`

/like

This allows other nice things ;)

@see otherMethod() :reverse:  (for example utf8encode()/utf8decode())

@see otherMethod() :equivalent: (for example array_chunk() (split an array), str_split() (split strings). Maybe not a good example)

@see otherMethod() :specilization: (for example strncmp() is a specilization of strcmp())

@see otherMethod() :generalization: (opposite of specilization)

@see otherMethod() :similar: (something like "alias", but with a minor difference. No example ;) Maybe strcmp()/strncmp() too. In fact the whole str*cmp()-family)

@see otherMethod() :related: (kind of how @see is right now)

I don't know, if I like the notation, but thats not the question right now, because I like the concept. And while I wrote this I realized, that this are examples, why @alias may be a bad idea: There are many many other useful relations between methods than only "alias".

 

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[Ryan Parman]

On Oct 11, 2012, at 11:20 AM, Sebastian Krebs <kreb...@gmail.com> wrote:

> However, do you really implement a method multiple times just because a developer cannot remember a (max) 5 characters method name?

Absolutely.

> This makes me think you assume, that your users wont read the API-doc, so why want to document the aliased-nature of both within the API-doc? And when they can't remember the methods, why should they even want to know, that a method is an alias of another one?

Earlier in my career, I spent 2 years as a Usability Analyst and User Researcher, conducting a variety of usability tests for various products and trying to learn as much as I could about how human beings process information.

In short: Humans are messy, scatter-brained, inconsistent and highly subjective. Pretty much the exact opposite of how a machine works.

Some people will read the docs, some people won't. Some people will remember one name, other people will remember the other. Some people come from other programming languages where the terminology in that community is different from this one (list vs. array, anyone?).

And not every method is concrete. When you're working with dynamic methods (via __call()), and you're already invoking the cost of a dynamic method anyway, creating aliases that do a better job mapping to what users (i.e., human beings) understand in their own personal mental model of the software is a positive move on behalf of the user. Especially in projects that are particularly large.

> Really: Your example is really no valid case for useful alias. There is absolutely no reason to habe both methods, except "some will remember x() better than y()" ...

Forgive me, but what I learned from usability testing is that this is *precisely* a valid case for a useful alias.

[Ryan Parman]

On Oct 11, 2012, at 1:40 PM, Mike van Riel <draco...@gmail.com> wrote:

> Also: what will happen if in 1 or 2 years someone comes along with a
> new strong case for a tag representing a relation type; are we going
> to write a new Core PSR to add the tag? An extension?

If it's warranted, sure.

> Example:
>
> `@see my_method() :alias: to provide a method that matches the Coding Standard`
>
> 2nd example:
>
> `@see http://manual.phpdoc.org :manual: to provide details regarding
> the use of phpDocumentor v1`

These are good examples. They address the problem, they're easy to write, and they're easily parseable.

[Ryan Parman]

On Oct 11, 2012, at 2:28 PM, Sebastian Krebs <kreb...@gmail.com> wrote:

> @see otherMethod() :reverse: (for example utf8encode()/utf8decode())
> @see otherMethod() :equivalent: (for example array_chunk() (split an array), str_split() (split strings). Maybe not a good example)
> @see otherMethod() :specilization: (for example strncmp() is a specilization of strcmp())
> @see otherMethod() :generalization: (opposite of specilization)
> @see otherMethod() :similar: (something like "alias", but with a minor difference. No example ;) Maybe strcmp()/strncmp() too. In fact the whole str*cmp()-family)
> @see otherMethod() :related: (kind of how @see is right now)

Okay, these are good examples.

But there are two things that I want to bring up. Let the flaming begin. :)

1. How is this _really_ any different from adding entirely new tags?

@reverse
@equivalent
@specialization
@generalization
@similar
@related

Practically speaking, how are these any different?

2. These new :<keyword>: tags will need to be supported and understood by documentation tools.

How is maintaining a list of supported keywords any different from (a) supporting the service shorthands I proposed for the @author tag, and (b) supporting the license shorthands that the PHPDoc PSR already supports for @license?

[Mike van Riel]

On Fri, Oct 12, 2012 at 9:41 AM, Ryan Parman <ry...@ryanparman.com> wrote:
> 1. How is this _really_ any different from adding entirely new tags?
>
> @reverse
> @equivalent
> @specialization
> @generalization
> @similar
> @related
>
> Practically speaking, how are these any different?

I see the following differences:

1. By keeping the list of tags short but allowing them to have
parameters you make it easier for code authors to remember which
options there are (feature bloat). Adding a tag for each relation type
would bloat the list and confuses the user (too much choice often
results in apathy). By providing a simple tag '@see' that may be used
without keyword and optionally adding a keyword for sub-clarification
you keep the process simple for those wanting simple and verbose for
those wanting verbose.

2. Extendability, the relation types do not necessarily have to be
limited to those in the PSR itself (or even mentioning them at all).
This allows a documentation generator the freedom to add their own
relation types and still provide a predictable experience for all
users and tools.

> 2. These new :<keyword>: tags will need to be supported and understood by documentation tools.
>
> How is maintaining a list of supported keywords any different from (a) supporting the service shorthands I proposed for the @author tag, and (b) supporting the license shorthands that the PHPDoc PSR already supports for @license?

You are comparing apples to oranges here;

* the @author 'shorthands' are proprietary and non-intuitive
substitutions for a standardized format (URI) just to save characters.
As I see it they serve no purpose other than having to type less but
make it more ambiguous
* the license shorthands are not an integral part of the PSR; they are
maintained by a third party and are used for reference (as with RFCs)

[Johannes Schmitt]

I don't think that many tags are the problem, but documentation of these tags is important.

Personally, I would actually prefer more tags which are more specific/descriptive over less tags with more arguments.

Johannes

[Sebastian Krebs]

2012/10/12 Ryan Parman <ry...@ryanparman.com>

On Oct 11, 2012, at 2:28 PM, Sebastian Krebs <kreb...@gmail.com> wrote:

> @see otherMethod() :reverse:  (for example utf8encode()/utf8decode())
> @see otherMethod() :equivalent: (for example array_chunk() (split an array), str_split() (split strings). Maybe not a good example)
> @see otherMethod() :specilization: (for example strncmp() is a specilization of strcmp())
> @see otherMethod() :generalization: (opposite of specilization)
> @see otherMethod() :similar: (something like "alias", but with a minor difference. No example ;) Maybe strcmp()/strncmp() too. In fact the whole str*cmp()-family)
> @see otherMethod() :related: (kind of how @see is right now)

Okay, these are good examples.

But there are two things that I want to bring up. Let the flaming begin. :)

1. How is this _really_ any different from adding entirely new tags?

@reverse
@equivalent
@specialization
@generalization
@similar
@related

Practically speaking, how are these any different?

Nobody (at least I wont ;)) wants to remember hundreds of tags just for documentation, especially when they are only used for one or two elements (there are not so many use cases for lets say @equivalent). I can imagine, that at the end nobody will use it, because @see is just enough for what I want. Yes, I'm lazy :)

The difference is, that instead of several (formal) independent tags you have one tag to remember and you can give it a further (formal) description, if you like. Also it "sounds" more natural: "See X(), because it's a specilization of this one" :)
It's easier to say "There is a relation to another method/function (@see) and if you like you can give them a type to describe it further."

-- "Ugh, what was the tag name again? Oh, well, I'll use @see. will work too and I can describe it anyway"

@see x() x() is alias of this one

-- or ;)

@see x() :alias:

And (probably a minor one): Parser doesn't have so much to do. They see "@see" and the special "@see"-Handler-Implementation does everything else.

Going a little step furth I think, the core set of tags should be as small as possible and in best case no tag should overlap with another one and no tag should be part of another. The last one is what happens here, when @alias (or whatever) is in fact a "@see" with a little bit more.

 

2. These new :<keyword>: tags will need to be supported and understood by documentation tools.

Not necessarily. In worst case they will treat it as part of the description. This means, the description will start with ":<keyword>:", what looks ugly, but doesn't really hurt. Kind of graceful fallback ;)

 

How is maintaining a list of supported keywords any different from (a) supporting the service shorthands I proposed for the @author tag, and (b) supporting the license shorthands that the PHPDoc PSR already supports for @license?

Why limiting? When I want to mark a relation with ":supersede:", why do you want to prohibit it? What seems useful is to discourage (or forbid) and encourage (or force ;)) several types (e.g. ":supersede: in favor of ":replace:") to avoid cluttering.

(a) As far as I can see this "services" are now "valid urls with (officially) existing schemes", which at least in theory includes every existing protocol, but except mailto: and http(s): they doesn't make much sense.

(b) The license shortnames are provided by a separate service (as far as I remember. If not, I guess it would be a good idea ;))

 

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[Sebastian Krebs]

2012/10/12 Johannes Schmitt <schmi...@gmail.com>

I don't think that many tags are the problem, but documentation of these tags is important.

Maybe "problem" is the wrong word, but whats the benefit in (lets say) 80 tags, where only 20 are used in the wild? Note, that @alias is a kind of sub-type to @see and I assume instead of searching for the best matching tag in a list most developers will take the best matching take from theire memory, which is often not the best choice and will be used inconsistent. Some will use @see with a description "alias of" and some will use @alias without description.

--
github.com/KingCrunch

[Ryan Parman]

On Oct 12, 2012, at 1:15 AM, Mike van Riel <draco...@gmail.com> wrote:

> 1. By keeping the list of tags short but allowing them to have
> parameters you make it easier for code authors to remember which
> options there are (feature bloat).

I've often seen the word "bloat" mis-attributed. Just to make sure we have the same definition, I do not equate bloat === more, but rather bloat === !usefulness.

> Adding a tag for each relation type
> would bloat the list and confuses the user (too much choice often
> results in apathy).

You're right about the "Paradox of Choice". (There's a good TED talk on that topic.) At the same time, there is an appropriate balance. Philosophically, having too few choices with too many optional parameters is equally confusing.

I believe that what we're discussing here is where that balance is. In both cases, users will still need to remember or have a reference for each keyword in the list. Whether that keyword is at the beginning of the line with an "@" prepended to it, or in the middle with ":" wrapped around it is, IMO, inconsequential.

We've not reduced the number of choices in either case.

> By providing a simple tag '@see' that may be used
> without keyword and optionally adding a keyword for sub-clarification
> you keep the process simple for those wanting simple and verbose for
> those wanting verbose.

As I mentioned above, I think there's a balance to be struck. It sounds as though you and I have a difference of opinion on where that balance lies.

> * the @author 'shorthands' are proprietary and non-intuitive
> substitutions for a standardized format (URI) just to save characters.
> As I see it they serve no purpose other than having to type less but
> make it more ambiguous

To be pedantic, they *are* valid URIs. They're just not URLs. And I would question your assessment of non-intuitiveness.

But I'm willing to acquiesce on that one.

> * the license shorthands are not an integral part of the PSR; they are
> maintained by a third party and are used for reference (as with RFCs)

True. So, how would this be different from creating a list maintained by a first/second-party and being used for reference?

[Ryan Parman]

On Oct 12, 2012, at 1:36 AM, Sebastian Krebs <kreb...@gmail.com> wrote:

> Note, that @alias is a kind of sub-type to @see and I assume instead of searching for the best matching tag in a list most developers will take the best matching take from theire memory, which is often not the best choice and will be used inconsistent. Some will use @see with a description "alias of" and some will use @alias without description.

First of all, we need to take a step back because this thread is quickly filling up with speculation and falsehoods.

1. In Mike's PHPDoc PSR document, @see isn't defined at all [1], so we can't draw our definition of @see from there.

2. If we can't refer to the PHPDoc PSR, we (arguably) should fall back to the de-facto PHPDoc standard.

In the phpDocumentor 1.x manual entry for @see [2], the definition is "Display a link to the documentation for an element". In my proposed spec for @alias, this is not the intention I've described. Therefore, it is not strictly a sub-type, but instead has a legitimately different purpose from displaying a link to the documentation of another element.

@alias being a subtype of @see is an argument that has been brought up in *this thread* as a discussion point, but it is by no means a canonical definition.

--
[1] https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md#716-see
[2] http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.see.pkg.html

[Mike van Riel]

On Fri, Oct 12, 2012 at 8:57 PM, Ryan Parman <ry...@ryanparman.com> wrote:
> On Oct 12, 2012, at 1:15 AM, Mike van Riel <draco...@gmail.com> wrote:
>
>> 1. By keeping the list of tags short but allowing them to have
>> parameters you make it easier for code authors to remember which
>> options there are (feature bloat).
>
> I've often seen the word "bloat" mis-attributed. Just to make sure we have the same definition, I do not equate bloat === more, but rather bloat === !usefulness.

Bloat means a to me that there are more features than can easily be
tracked by a user; independent of usefulness. And thus decreasing
usefulness along the way.

>> Adding a tag for each relation type
>> would bloat the list and confuses the user (too much choice often
>> results in apathy).
>
> You're right about the "Paradox of Choice". (There's a good TED talk on that topic.) At the same time, there is an appropriate balance. Philosophically, having too few choices with too many optional parameters is equally confusing.
>
> I believe that what we're discussing here is where that balance is. In both cases, users will still need to remember or have a reference for each keyword in the list. Whether that keyword is at the beginning of the line with an "@" prepended to it, or in the middle with ":" wrapped around it is, IMO, inconsequential.
>
> We've not reduced the number of choices in either case.

I disagree here; the :type: argument serves as a 'nesting level' and
still helps to limit choice.

>> By providing a simple tag '@see' that may be used
>> without keyword and optionally adding a keyword for sub-clarification
>> you keep the process simple for those wanting simple and verbose for
>> those wanting verbose.
>
> As I mentioned above, I think there's a balance to be struck. It sounds as though you and I have a difference of opinion on where that balance lies.
>
>
>> * the @author 'shorthands' are proprietary and non-intuitive
>> substitutions for a standardized format (URI) just to save characters.
>> As I see it they serve no purpose other than having to type less but
>> make it more ambiguous
>
> To be pedantic, they *are* valid URIs. They're just not URLs. And I would question your assessment of non-intuitiveness.

Agreed; I meant URL. The non-intuitiveness is with regards that there
is no standard to rely on and no common use in the field.

>
>> * the license shorthands are not an integral part of the PSR; they are
>> maintained by a third party and are used for reference (as with RFCs)
>
> True. So, how would this be different from creating a list maintained by a first/second-party and being used for reference?

That the third-party registry already exists; is feature complete and
is maintained by more people and thus more accurate?

[Mike van Riel]

On Fri, Oct 12, 2012 at 9:10 PM, Ryan Parman <ry...@ryanparman.com> wrote:
> On Oct 12, 2012, at 1:36 AM, Sebastian Krebs <kreb...@gmail.com> wrote:
>
>> Note, that @alias is a kind of sub-type to @see and I assume instead of searching for the best matching tag in a list most developers will take the best matching take from theire memory, which is often not the best choice and will be used inconsistent. Some will use @see with a description "alias of" and some will use @alias without description.
>
> First of all, we need to take a step back because this thread is quickly filling up with speculation and falsehoods.
>
> 1. In Mike's PHPDoc PSR document, @see isn't defined at all [1], so we can't draw our definition of @see from there.

Correct, this part is still work in progress as described in an earlier thread.

> 2. If we can't refer to the PHPDoc PSR, we (arguably) should fall back to the de-facto PHPDoc standard.
>
> In the phpDocumentor 1.x manual entry for @see [2], the definition is "Display a link to the documentation for an element". In my proposed spec for @alias, this is not the intention I've described. Therefore, it is not strictly a sub-type, but instead has a legitimately different purpose from displaying a link to the documentation of another element.
>
> @alias being a subtype of @see is an argument that has been brought up in *this thread* as a discussion point, but it is by no means a canonical definition.

I am having trouble seeing alias as something substantially different
as a link to the documentation of another element. @see defines a
relation between the current location and another. An alias just names
that relation

[Ryan Parman]

On Oct 12, 2012, at 12:39 PM, Mike van Riel <draco...@gmail.com> wrote:

> I am having trouble seeing alias as something substantially different
> as a link to the documentation of another element. @see defines a
> relation between the current location and another. An alias just names
> that relation

Linking to the documentation of another element isn't *at all* how I intend to surface this data. But this is an implementation detail, which is why I left it out of my proposal.

In terms of exposing the relationships to the consumer of the documentation, support for @see and support for @alias are handled *very* differently from each other.

[Mike van Riel]

As I see it the abstract concept of 'alias' is nothing more than
indicating that two entities are related by being eachother's equals,
or that one represents the other.
@see (also) represents a relation between two elements (one refers to
the other; hence relationship) without specifying how these two are
related.

Thus I do not see what you mean; I honestly do not see why you say
that an alias is not (merely) a type of relationship.

[Ryan Parman]

On Oct 12, 2012, at 1:37 PM, Mike van Riel <draco...@gmail.com> wrote:

> Thus I do not see what you mean; I honestly do not see why you say
> that an alias is not (merely) a type of relationship.

I'm not arguing that it's not a relationship. It clearly is.

What I'm arguing (at this point, anyway) is that there is currently *no text* that states that @see is about defining relationships. The current definition of @see is about linking to the documentation of another element -- not being related to it.

Regardless, even if we use @see to describe an alias relationship, we still don't have either (a) an agreed-upon syntax for annotating that relationship, or (b) a list of available relationships that tool developers can choose to add support for.

Perhaps figuring out those two things are the next logical steps in moving this discussion forward.

[Mike van Riel]

My person take is that the @see tag should be altered to be able to
optionally support a 'type'. This would mean expanding the @see
definition from

@see <"Type"> [description]

to

@see <"Type"> [:relation:] [description]

Or a variant where the delimiter varies.

The delimiter's function is twofold:

1) differentiate between the 'plain version' without relation type and
that with the type
2) provide the user (and to an extent the parser) with a clear
indication what type of relation is represented; the delimiter can
'guide the eye' (that is also why I chose for a symmetrical delimiter)

I am in doubt whether it is a good thing to offer a list of types to
choose from. This is typically a categorization that is not
exhaustive.
It could be wise to have a separate PSR, or registry, maintained for
that purpose or provide a few types as examples but not as exhaustive
listing.
This may provide documentation tools a greater degree of freedom