Skip to:
Content

Opened 2 years ago

Closed 2 years ago

Last modified 19 months ago

#6576 closed defect (bug) (fixed)

@since standard not parseable with phpDocumentor 2

Reported by: DJPaul Owned by: tw2113
Milestone: 2.4 Priority: normal
Severity: normal Version:
Component: Core Keywords: dev-feedback
Cc: stephen@…

Description

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.

Change History (38)

#1 @DJPaul
2 years ago

  • Keywords dev-feedback added

#2 @tw2113
2 years ago

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

#3 @boonebgorges
2 years ago

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.

#4 @netweb
2 years ago

  • Cc stephen@… added

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

#5 @r-a-y
2 years ago

I also vote for the second option.

#6 @mercime
2 years ago

Thanks for working on developer.buddypress.org!!

Ditto

#7 @DJPaul
2 years ago

  • Milestone changed from BuddyPress.org to 2.4

This ticket was mentioned in Slack in #buddypress by djpaul. View the logs.


2 years ago

This ticket was mentioned in Slack in #bbpress by netweb. View the logs.


2 years ago

#10 follow-up: @johnjamesjacoby
2 years ago

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...)

#11 @DJPaul
2 years ago

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).

#12 @DJPaul
2 years ago

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/

#13 @netweb
2 years ago

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

https://cloudup.com/cmjtWEccimi

#14 in reply to: ↑ 10 @tw2113
2 years ago

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.

#15 follow-up: @DJPaul
2 years ago

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

#16 in reply to: ↑ 15 @netweb
2 years ago

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:

#17 @netweb
2 years ago

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.

This ticket was mentioned in Slack in #buddypress by tw2113. View the logs.


2 years ago

#19 @tw2113
2 years ago

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.

#20 @johnjamesjacoby
2 years ago

  • Owner set to tw2113
  • Status changed from new to assigned

#21 @tw2113
2 years ago

In 10077:

Standardizing our @since tags for the Activity component.

See #6576.

#22 @tw2113
2 years ago

In 10096:

Standardizing our @since tags for the Forums component.

See #6576

#23 @tw2113
2 years ago

In 10100:

Standardizing our @since tags for the Blogs component.

See #6576

#24 @tw2113
2 years ago

In 10108:

Standardizing our @since tags for the Core component.

See #6576.

#25 @tw2113
2 years ago

In 10137:

Standardizing our @since tags for the Settings component.

See #6576.

#26 @tw2113
2 years ago

In 10138:

Standardizing our @since tags for the Notifications component.

See #6576

#27 @tw2113
2 years ago

In 10139:

Standardizing our @since tags for the Messages component.

See #6576.

#28 @tw2113
2 years ago

In 10140:

Standardizing our @since tags for the XProfile component.

See #6576.

#29 @tw2113
2 years ago

In 10141:

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

See #6576.

#30 @tw2113
2 years ago

In 10142:

Finishing off the XProfile class files for @since changes.

See #6576.

#31 @tw2113
2 years ago

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

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

#32 @tw2113
2 years ago

In 10146:

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

See #6576.

#33 @tw2113
2 years ago

In 10147:

Standardizing our @since tags for the Friends Component.

See #6576.

#34 @tw2113
2 years ago

In 10148:

Standardizing our @since tags for the Groups Component.

See #6576.

#35 @tw2113
2 years ago

In 10149:

Standardizing our @since tags for the Members Component.

See #6576.

#36 @tw2113
2 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 10150:

Standardizing our @since tags for the Templates Component.

Fixes #6576.

#37 @djpaul
2 years ago

In 10246:

Standardise more phpDoc at-since tags

See #6576

#38 @DJPaul
19 months ago

  • Component changed from Component - Any/All to Core
Note: See TracTickets for help on using tickets.