PHP documentation needed through-out BP

[johnjamesjacoby]

We need to sweep through BP and start phpDoc'ing everything. That includes going function by function and updating outdated docs.

[johnjamesjacoby]

Could be a Google Code In opportunity. Switching to task and changing to major, as documentation has always been one of our weaker points.

[johnjamesjacoby]

Google Code in is over. Would absolutely adore a patch full of phpDoc.

[DJPaul]

Moving to future release to clear out the 1.3 milestone but ticket obviously still on-going

[Backie]

This is something I may actually be able to help with, I'll be going over all the code and documenting it anyway since we'll be using it for a major project so some PHPDocs at the same time seems like 2 birds, 1 stone.

[Backie]

Noticed the @package tag isn't being properly used.

@package BuddyPress Core

As stated in ​http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.package.pkg.html it has to be one word alphanumeric and _-[]. Suggest change it to BuddyPress_Component.

[Backie]

BP_Core_User

[Backie]

BP_Core_Notification

[Backie]

BP_Button

[Backie]

bp-core-avatars.php

[DJPaul]

I've just seen these -- trac doesn't send notification emails when attaching files, only when leaving a comment. Taking a look now!

[djpaul]

(In [4462]) Add some tasty phpdoc. Props Backie, see #2345

[cnorris23]

bp-activity folder

[cnorris23]

PHP doc for the entirety of the bp-activity folder. It's by no mean complete, but it's a good start. I'm going to keep patching like this, and hopefully as the patches go in, more people will help clean up. It's a daunting task to start from scratch, so I figure I'd mostly work on getting the groundwork laid. I can break this, and future patches up by file if preferred. Also, I should be noted that I more or less just rounded to the lowest version on the @since doc. Furthermore, I added @todo notes were I noticed weirdness in the code, added @deprecated notes where it seemed appropriate.

[boonebgorges]

(In [5109]) Adds PHPDoc throughout the activity component. References #2345. Turbo props cnorris23

[cnorris23]

bp-blogs folder

[cnorris23]

Blogs component is now available. In the interest of full disclosure, I wanted to note that I included a basic fix for #3328 since it was closed as fixed, but nothing was really done. The fix is nothing like any of the included patches. I just changes:

wp_cache_delete( 'bp_blogs_of_user_' . $user_id, 'bp' );

to

wp_cache_delete( 'bp_blogs_of_user_' . $user_id . 'inc_hidden', 'bp' );.

The first key doesn't exist.

[DJPaul]

Cool stuff, thanks. I'll let someone else look at it as I haven't time.

A general comment, not aimed at you or this patch specifically, is that the @subpackage values look messy. Plus I dislike camelcase!

`

• @package BuddyPress
• @subpackage ActivityActions

`

Can we split the words in the @subpackages with a hyphen or a space, or something?

[cnorris23]

Spaces are invalid, as it must be one word, but hyphens and underscores work. I was just going off of what jjj was doing with the bbPress plugin. I'm with you, that they don't look great. My suggestion is to either drop the component name, as the filename gives that away,

• @package BuddyPress
• @subpackage Actions

or to use underscores

• @package BuddyPress
• @subpackage Activity_Actions

[boonebgorges]

I assume that the goal of the @subpackage line is to help programs like PHPXref to catalog and organize functions - it's not really meant to benefit humans looking directly at the code (who can see both the component name and the 'actions' bit by looking at the file tree). For that reason, we shouldn't drop the component name, since it will group functions from bp-groups-actions.php with those from bp-activity-actions.php, etc.

If anything, I think we should go with just the component name. I'd argue that the -actions functions are not really a sub-*package* at all, as they don't really stand alone in any meaningful sense.

[cnorris23]

You make a good point boonebgorges. So is this the conscensus? Do we just use component names for subpackage?

[cnorris23]

bp-blogs folder with updated subpackage

[cnorris23]

Update Blogs component @subpackage to component name only

[cnorris23]

I should add that the patch applies cleanly to both trunk and branch, in case you devs want to add it in for 1.5.1.

[DJPaul]

Declaring this complete as of BP 1.5. We put serious effort into phpDoc during that release, and it's become second-nature to document any new functions that go into core.