PHPDoc PSR: @license and SPDX

[Mike van Riel]

Patrick,

I have split this discussion off from the @author discussion given
that it is effectively offtopic.

Please see the inline comments for my answers to your questions:

On Fri, Oct 12, 2012 at 12:08 AM, Patrick Mulvey <pdmu...@gmail.com> wrote:
>
> On Thursday, October 11, 2012 10:17:54 PM UTC+1, Mike van Riel wrote:
>> On Thu, Oct 11, 2012 at 11:11 PM, Patrick Mulvey <pdmu...@gmail.com>
>> wrote:
>> Please read the text of @license; the recommended way is just to add a
>> URL and a description. The code author MAY choose to adopt spdy but is
>> in no way required or even encouraged to do so.
>
> Yeah, I've read it and I understand that it's a discouraged option. Can I
> ask why it's an option at all? Especially if it's not encouraged? What's the
> benefit over just using URLs? If I'm reading it right, the documentation
> tool would have to go and look up the URL in the registry based on the
> identifier. That sounds like a lot of effort.

To answer the why: As far as I know several projects out there already
use the URL-less version of @license. Whatever there reason may be, I
believe it to be wrong to ignore this. In a sense not using a URL is
more user-friendly as long as is standardized what specific terms
mean. This is where SPDX comes in; they provide a fully annotated
registry of names, together with accepted abbreviations.

A documentation tool would only have to retrieve the complete contents
every so often and store it in a cache file or some other mechanism, I
do not see the effort in this.
And it is not required to include support for this in your
documentation project, the wording specifically states that this is
optional, both for consumer and producer.

(also: not encouraged !== discouraged; an important semantic difference)

>> ```
>> Instead of providing a URL MAY an identifier as identified in the SPDX
>> Open Source License Registry be provided and SHOULD this be
>> interpreted as if having the URL mentioned in the registry.
>> ```
>
> Incidentally, I think you have a few typos in this paragraph. Shouldn't it
> read "Instead of providing a URL, an identifier as identified in the SPDX
> Open Source License Registry MAY be provided, and this SHOULD be interpreted
> as if having the URL mentioned in the registry"? In it's current form this
> sentence a bit confusing.

Thank you, I will fix this.

>> p.s. SPDX is maintained/supported by the Linux Foundation, so it
>> should have some merit ;)
>
> I agree the Linux Foundation is a trustworthy organisation, but they can
> still make mistakes, decide to stop maintaining the list, move the list to a
> different location, or change the format of the list.

The alternative would be that each documentation tool were to
implement their own registry where: they make mistakes, will certainly
take no effort to maintain the list, may move the list to a different
location or change the format. The other alternative would be to add a
list in this specification but that wouldn't be maintained as well
since a PSR is frozen after being accepted.

So, why not use a centralized trustworthy registry? In my opinion not
doing so would be the same as saying: I won't link to an RFC; I'll
write my own.

[Patrick Mulvey]

On Friday, October 12, 2012 7:07:21 AM UTC+1, Mike van Riel wrote:

Patrick,

I have split this discussion off from the @author discussion given
that it is effectively offtopic.

Please see the inline comments for my answers to your questions:

Thanks for taking the time to reply in such detail. 

 

On Fri, Oct 12, 2012 at 12:08 AM, Patrick Mulvey <pdmu...@gmail.com> wrote:
>
> On Thursday, October 11, 2012 10:17:54 PM UTC+1, Mike van Riel wrote:
>> On Thu, Oct 11, 2012 at 11:11 PM, Patrick Mulvey <pdmu...@gmail.com>
>> wrote:
>> Please read the text of @license; the recommended way is just to add a
>> URL and a description. The code author MAY choose to adopt spdy but is
>> in no way required or even encouraged to do so.
>
> Yeah, I've read it and I understand that it's a discouraged option. Can I
> ask why it's an option at all? Especially if it's not encouraged? What's the
> benefit over just using URLs? If I'm reading it right, the documentation
> tool would have to go and look up the URL in the registry based on the
> identifier. That sounds like a lot of effort.

To answer the why: As far as I know several projects out there already
use the URL-less version of @license. Whatever there reason may be, I
believe it to be wrong to ignore this. In a sense not using a URL is
more user-friendly as long as is standardized what specific terms
mean. This is where SPDX comes in; they provide a fully annotated
registry of names, together with accepted abbreviations.

A documentation tool would only have to retrieve the complete contents
every so often and store it in a cache file or some other mechanism, I
do not see the effort in this.
And it is not required to include support for this in your
documentation project, the wording specifically states that this is
optional, both for consumer and producer.

Fair enough. I can certainly see the logic in accommodating what people are already doing. 

I guess the effort is retrieving and parsing the file. Setting up a cache is an additional task too. If I'm offline and the list cannot be retrieved, the tool has to figure out a friendly way to communicate this. Testing all of that could be a bit painful. But as you said, this feature is optional. 

 

(also: not encouraged !== discouraged; an important semantic difference)

True.

 

>> ```
>> Instead of providing a URL MAY an identifier as identified in the SPDX
>> Open Source License Registry be provided and SHOULD this be
>> interpreted as if having the URL mentioned in the registry.
>> ```
>
> Incidentally, I think you have a few typos in this paragraph. Shouldn't it
> read "Instead of providing a URL, an identifier as identified in the SPDX
> Open Source License Registry MAY be provided, and this SHOULD be interpreted
> as if having the URL mentioned in the registry"? In it's current form this
> sentence a bit confusing.

Thank you, I will fix this.

>> p.s. SPDX is maintained/supported by the Linux Foundation, so it
>> should have some merit ;)
>
> I agree the Linux Foundation is a trustworthy organisation, but they can
> still make mistakes, decide to stop maintaining the list, move the list to a
> different location, or change the format of the list.

The alternative would be that each documentation tool were to
implement their own registry where: they make mistakes, will certainly
take no effort to maintain the list, may move the list to a different
location or change the format. The other alternative would be to add a
list in this specification but that wouldn't be maintained as well
since a PSR is frozen after being accepted.

So, why not use a centralized trustworthy registry? In my opinion not
doing so would be the same as saying: I won't link to an RFC; I'll
write my own.

Fair enough. I'm just always wary of creating external dependencies like this. But you've convinced me that in this case they're a necessary evil.