@since standard not parseable with phpDocumentor 2

[DJPaul]

For 2.4, I'm going to help get devhub set up for BuddyPress (i.e. developer.wordpress.org), and a lot of this involves running a WP-Parser project on our code base, and it auto-creates documentation from that. For the code, this is done via the phpDocumentor parser libraries.

I've been testing this, and an issue that's come up immediately is our @since tags. @since BuddyPress (1.0) YOLO does not confirm to the relevant standards, see ​http://phpdoc.org/docs/latest/references/phpdoc/tags/since.html, which means the @since tags are not parsed/extracted correctly.

There are two ways forward: 1) add filters to WP-Parser to parse our non-standard @since tag (PHP standards, not just WordPress'), or 2) change our @since tags back to what they were: @since 1.0 YOLO.

I am inclined to suggest the latter because I don't think we win anything from not sticking to PHP standards in this area.

[tw2113]

Ooh, lots of potential work there. Doesn't matter to me either way.

[boonebgorges]

Thanks for working on developer.buddypress.org!!

I also lean toward option 2. It'd be nice for johnjamesjacoby to weigh in - he originally introduced the current syntax, and I can't remember whether it was to placate an IDE, or just for aesthetics, or what.

[netweb]

JJJ Wrote in Slack ​https://wordpress.slack.com/archives/buddypress/p1438177016000411

"Our @since was designed to act as a namespace when inside WordPress. It was always a hack, but at the time of its inception, it wasn't out of spec."

The rest of the @since chat in #BuddyPress -> ​https://wordpress.slack.com/archives/buddypress/p1438167747000382

[r-a-y]

I also vote for the second option.

[mercime]

Thanks for working on developer.buddypress.org!!

Ditto

[johnjamesjacoby]

Our bespoke format came from the confluence of a few issues I was having at the time:

• phpDocumentor had no way to differentiate @since tags between dependencies
• IDE's weren't able to discern dependency between projects and functions
• Searching an entire installation for something like @since 2.0 would bring up results for WordPress, BuddyPress, and bbPress, which was a frustrating developer experience
• It was my first real deep dive into exactly what the phpDocumentor spec was, and I overlooked exactly how @since worked (and did not work)

How about:

• @since 2.7.0 BuddyPress (rxxxx) - Whatever the details are where the (rxxxx) is optional. We've debated the usefulness of including the changeset in the past, but I have a tendency to use them in bbPress quite a bit for looking back in time very easily without loading up annotations every time.
• @package BuddyPress at the top of each file in the PHPDoc block
• @subpackage Functions underneath @package where "Functions" is some descriptor that works across all components (Actions, Cache, Classes, Assets, Filters, Functions, Loader, Notifications, Screens, TemplateTags, Widgets, etc...)

[DJPaul]

I have been thinking about about package/subpackage so glad to see you have too -- I think these help categorise the generated documentation so win/win, but I would like that discussed in another ticket to keep this one small and focused on @since (also, because I haven't got my thoughts together about it yet, so I can't reply immediately). I'll copy your comments over when I open the other ticket. :)

I am against including the SVN revision number; I don't think we need to re-invent SVN blame and I'm not convinced it would be useful for the majority of developers. Interested to see what the others think.

I could live with @since 2.7.0 BuddyPress , but there's a small issue with this. Multiple @since tags are supported, which act as a kind-of changelog. Here's an example from BuddyPress where we do this already:

 * @since BuddyPress (1.6.0)
 * @since BuddyPress (2.3.0) We only support Akismet 3+.

...would look like...

 * @since 1.6.0 BuddyPress
 * @since 2.3.0 BuddyPress We only support Akismet 3+.

These descriptions show up inside the WP-Parser generated pages (this is the tool that powers developer.wordpress.org).

[DJPaul]

I found an example of multiple @since in the WordPress documentation to help clarify what I'm trying to say:

​https://developer.wordpress.org/reference/hooks/admin_color_scheme_picker/

[netweb]

A quick collection of screenshots of developer.bbpress.org using @since x.y bbPress (r98765) YOLO :

​https://cloudup.com/cmjtWEccimi

[tw2113]

Replying to johnjamesjacoby:

How about:

• @since 2.7.0 BuddyPress (rxxxx) - Whatever the details are where the (rxxxx) is optional. We've debated the usefulness of including the changeset in the past, but I have a tendency to use them in bbPress quite a bit for looking back in time very easily without loading up annotations every time.
• @package BuddyPress at the top of each file in the PHPDoc block
• @subpackage Functions underneath @package where "Functions" is some descriptor that works across all components (Actions, Cache, Classes, Assets, Filters, Functions, Loader, Notifications, Screens, TemplateTags, Widgets, etc...)

I am going to start looking into changing things based on these guidelines. I have some time off to start the week which would make for some good contribution time. We will do this for both function declarations and hooks.

[DJPaul]

Worth taking a look at the as-yet-unratified PSR-5 standard and considering what we might have to do in the future if subpackage is deprecated (or is it worth us moving off that ship now, and delimiting a hierarchy with forward-slashes in the package section?), etc

[netweb]

Replying to DJPaul:

Worth taking a look at the as-yet-unratified PSR-5 standard and considering what we might have to do in the future if subpackage is deprecated (or is it worth us moving off that ship now, and delimiting a hierarchy with forward-slashes in the package section?), etc

For those playing at home, the proposed PSR-5 is here:

• ​https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

[netweb]

Related: ​#WP31340

Quoting DrewAPicture

I would encourage you to use or not use @subpackage tags at your discretion.

Part of the issue we have in core is that our parser currently only supports phpDocumentor 1.0 in which name-spaced @package tags are not supported and @subpackage tags are not deprecated. Thus the note in the WordPress documentation standards.

When we opted to write our standard, we heavily leaned toward historical precedence of the code base, and that's something that we've maintained through today. The benefit of approaching change in this way is that later, when the PSR-5 recommendations are finalized and approved, it will be that much simpler for us to adjust to those new recommendations.

[tw2113]

Discussed in 08-26-15 dev chat that we would go with just the version number in the @since tags. Extra notes can be left in the long description, as necessary.

[tw2113]

In 10077:

Standardizing our @since tags for the Activity component.

See #6576.

[tw2113]

In 10096:

Standardizing our @since tags for the Forums component.

See #6576

[tw2113]

In 10100:

Standardizing our @since tags for the Blogs component.

See #6576

[tw2113]

In 10108:

Standardizing our @since tags for the Core component.

See #6576.

[tw2113]

In 10137:

Standardizing our @since tags for the Settings component.

See #6576.

[tw2113]

In 10138:

Standardizing our @since tags for the Notifications component.

See #6576

[tw2113]

In 10139:

Standardizing our @since tags for the Messages component.

See #6576.

[tw2113]

In 10140:

Standardizing our @since tags for the XProfile component.

See #6576.

[tw2113]

In 10141:

Adding CSS/JS files that were skipped on first pass, getting some missed spots in php files.

See #6576.

[tw2113]

In 10142:

Finishing off the XProfile class files for @since changes.

See #6576.

[tw2113]

By my notes, we have the following components/file remaining for @since revision.

BP-Friends
BP-Groups
BP-Members
BP-Templates
bp-loader.php

[tw2113]

In 10146:

Standardizing our @since tags for the bp-loader.php file.

See #6576.

[tw2113]

In 10147:

Standardizing our @since tags for the Friends Component.

See #6576.

[tw2113]

In 10148:

Standardizing our @since tags for the Groups Component.

See #6576.

[tw2113]

In 10149:

Standardizing our @since tags for the Members Component.

See #6576.

[tw2113]

In 10150:

Standardizing our @since tags for the Templates Component.

Fixes #6576.

[djpaul]

In 10246:

Standardise more phpDoc at-since tags

See #6576