PHPDoc Improvements

[espellcaste]

Placeholder ticket to hold all commits/changes related to PHPDoc to the 10.0.0 milestone.

PHPDoc changes only unrelated to any other ticket already in the milestone.

[imath]

Congrats for opening this ticket, there are a lot of missing DocBlocks in BP Nouveau 😬

[espellcaste]

In 13089:

Making PHPDoc Improvements to several files.

See #8553

[espellcaste]

In 13090:

Making PHPDoc Improvements to the BP Settings files.

See #8553

[espellcaste]

In 13091:

Making PHPDoc Improvements to the BP Notifications (component) files.

See #8553

[espellcaste]

In 13092:

Making PHPDoc Improvements to the BP Friends (component) files.

Also, adding several minor PHP changes.

See #8553

[espellcaste]

In 13096:

Making PHPDoc Improvements to the BP Messages (component) files.

Also, adding several minor PHP changes.

See #8553

[espellcaste]

In 13105:

Making PHPDoc Improvements to the BP Members (component) files.

Also, adding several minor PHP changes.

See #8553

[espellcaste]

In 13109:

Making PHPDoc Improvements to the class-buddypress.php file.

Also, adding several minor PHP changes.

Props imath

Fixes #8198 and see #8553

[imath]

Let's carry on working on this during next release

[espellcaste]

Not a lot of progress in this release. But carry the ticket on for the next release.

• As titled;
• Removing $bp when not used on the function/method;
• Minor tweaks.

Trac ticket: ​https://buddypress.trac.wordpress.org/ticket/8553

There are a lot of action callbacks being misused.

This pull request:

• removes the @return PHPdoc in functions without returned values, only with side effects;
• remove boolean values from functions without returned values, only with side effects;
• Update add_action to add_filter where applicable.

Trac ticket: ​https://buddypress.trac.wordpress.org/ticket/8553

@imath I did some quick preliminary testing locally and didn't see any issues.

If you could check/test as well, that'd be great. 💯

my concern is if a plugin is using this function to actually get a returned value it might generate issues with it.

I agree! I have other ways (more verbose) to address the PHPDoc issues without changing the examples you raised.

But I still think those examples are incorrect, they should not be returning anything, since they are being used to register/instantiate classes to BuddyPress itself. So if anyone is using them, they are doing it incorrectly.

bp_notifications_delete_notifications_on_user_delete is a good example. It currently has a side effect, AND it has a returned value. But when hooking into the do_action, the returned value has no usage.

This I think was a flaw in the design (its usage). Making a getter/setter function and using it in a do_action hook.

Trac ticket: ​https://buddypress.trac.wordpress.org/ticket/8553

[espellcaste]

In 13405:

Adding PHPDoc Improvements to the Blogs (component) files.

Props imath

Closes ​https://github.com/buddypress/buddypress/pull/56
See #8553

Trac ticket: ​https://buddypress.trac.wordpress.org/ticket/8553

Hi @renatonascalves

I tested things I had a concerned about. No side effects, so it's good to go. About bp_notifications_delete_notifications_on_user_delete() I've added a suggestion to deal with it. Thanks again for your work on it.

@imath Could you give another pass/look?

[espellcaste]

Closing in favor of #9164