Inline documentation initiative

During the 1.9 development cycle, BuddyPress’s inline documentation coverage increased dramatically. (See #5022.) Check out the stats:

• Version 1.8: 19294 lines of comments/docs for 42093 lines of PHP code (~45% ratio)
• Version 1.9: 27544 lines of comments/docs for 45115 lines of PHP code (~61% ratio)

The main push during 1.9 was docblocks for functions, classes, and methods – adding those that were missing, and correcting those that were incomplete/incorrect/inconsistent. Roughly half of the codebase now has complete docblock coverage: bp-activity, bp-blogs, bp-core, bp-forums, and some of bp-groups.

But there’s much more to do. Docblocks still have to be written/updated for roughly half of BuddyPress. And we have precisely zero inline documentation for our many action and filter hooks.

Let’s finish this job during the first part of 2014. In the spirit of WordPress’s recent hook documentation project, I’d like to call for volunteers to contribute to BP’s inline documentation.

How to contribute

1. Leave a comment on this post with the file(s) you’re claiming. You are encouraged to claim just a few files at a time (keeping in mind that some are much larger than others, and will take much more time to document).
2. Get an svn or git checkout of BuddyPress.
3. Edit the file with your new and improved documentation. Here is BuddyPress’s documentation standards page. As noted, we defer to WordPress’s PHP documentation standards in most cases.
4. Open a new Trac ticket. Title it: “Inline documentation: bp-xprofile/bp-xprofile-functions.php” (with the correct name of the file/s you’ve chosen).
5. Generate a diff file and attach it to the ticket and add the keyword “has-patch”.
6. Add your wordpress.org username or email address to the CC: field so you’ll receive activity notifications for your ticket.

A member of the core team will verify your patch and commit it as soon as possible.

A note to potential contributors: This is a great way to learn more about how BuddyPress works. Don’t be daunted by the prospect of documenting files you’ve never seen before; in most cases, it should be fairly straightforward to read what’s happening just by looking at the code or existing docs. Also, don’t feel as if you have to document everything in one go: doing part of a file, or just the docblocks, or just the hooks, is welcome.

The list

File names in italics are “checked out” by another contributor. File names that are struck out are considered completed for the purposes of our project. The “Docblocks” and “Hooks” tags show you when a file is partially done (and make it a bit easier for you to do just one aspect of a given file at a time). As people contribute, I’ll also list props here. (bp-default and the test suite are excluded from the list.)

• bp-activity/bp-activity-actions.php – Docblocks · Hooks
• bp-activity/bp-activity-admin.php – Docblocks · Hooks
• bp-activity/bp-activity-akismet.php – Docblocks · Hooks
• bp-activity/bp-activity-cache.php – Docblocks · Hooks
• bp-activity/bp-activity-classes.php – Docblocks · Hooks
• bp-activity/bp-activity-filters.php – Docblocks · Hooks
• bp-activity/bp-activity-functions.php – Docblocks · Hooks
• bp-activity/bp-activity-loader.php – Docblocks · Hooks
• bp-activity/bp-activity-notifications.php – Docblocks · Hooks
• bp-activity/bp-activity-screens.php – Docblocks · Hooks
• bp-activity/bp-activity-template.php – Docblocks · Hooks
• bp-blogs/bp-blogs-actions.php – Docblocks · Hooks
• bp-blogs/bp-blogs-activity.php – Docblocks · Hooks
• bp-blogs/bp-blogs-buddybar.php – Docblocks · Hooks
• bp-blogs/bp-blogs-cache.php – Docblocks · Hooks
• bp-blogs/bp-blogs-classes.php – Docblocks · Hooks
• bp-blogs/bp-blogs-filters.php – Docblocks · Hooks
• bp-blogs/bp-blogs-functions.php – Docblocks · Hooks
• bp-blogs/bp-blogs-loader.php – Docblocks · Hooks
• bp-blogs/bp-blogs-screens.php – Docblocks · Hooks
• bp-blogs/bp-blogs-template.php – Docblocks · Hooks
• bp-blogs/bp-blogs-widgets.php – Docblocks · Hooks
• bp-core/admin/bp-core-actions.php – Docblocks · Hooks
• bp-core/admin/bp-core-components.php – Docblocks · Hooks
• bp-core/admin/bp-core-functions.php – Docblocks · Hooks
• bp-core/admin/bp-core-schema.php – Docblocks · Hooks
• bp-core/admin/bp-core-settings.php – Docblocks · Hooks
• bp-core/admin/bp-core-slugs.php – Docblocks · Hooks
• bp-core/bp-core-actions.php – Docblocks · Hooks
• bp-core/bp-core-admin.php – Docblocks · Hooks
• bp-core/bp-core-adminbar.php – Docblocks · Hooks
• bp-core/bp-core-avatars.php – Docblocks · Hooks
• bp-core/bp-core-buddybar.php – Docblocks · Hooks
• bp-core/bp-core-cache.php – Docblocks · Hooks
• bp-core/bp-core-caps.php – Docblocks · Hooks
• bp-core/bp-core-catchuri.php – Docblocks · Hooks
• bp-core/bp-core-classes.php – Docblocks · Hooks
• bp-core/bp-core-component.php – Docblocks · Hooks
• bp-core/bp-core-cssjs.php – Docblocks · Hooks
• bp-core/bp-core-dependency.php – Docblocks · Hooks
• bp-core/bp-core-filters.php – Docblocks · Hooks
• bp-core/bp-core-functions.php – Docblocks · Hooks
• bp-core/bp-core-loader.php – Docblocks · Hooks
• bp-core/bp-core-moderation.php – Docblocks · Hooks
• bp-core/bp-core-options.php – Docblocks · Hooks
• bp-core/bp-core-template-loader.php – Docblocks · Hooks
• bp-core/bp-core-template.php – Docblocks · Hooks
• bp-core/bp-core-theme-compatibility.php – Docblocks · Hooks
• bp-core/bp-core-update.php – Docblocks · Hooks
• bp-core/bp-core-widgets.php – Docblocks · Hooks
• bp-core/bp-core-wpabstraction.php – Docblocks · Hooks
• bp-core/deprecated/1.2.php – Docblocks · Hooks
• bp-core/deprecated/1.5.php – Docblocks · Hooks
• bp-core/deprecated/1.6.php – Docblocks · Hooks
• bp-core/deprecated/1.7.php – Docblocks · Hooks
• bp-forums/bp-forums-actions.php – Docblocks · Hooks
• bp-forums/bp-forums-bbpress-sa.php – Docblocks · Hooks
• bp-forums/bp-forums-bbpress.php – Docblocks · Hooks
• bp-forums/bp-forums-filters.php – Docblocks · Hooks
• bp-forums/bp-forums-functions.php – Docblocks · Hooks
• bp-forums/bp-forums-loader.php – Docblocks · Hooks
• bp-forums/bp-forums-screens.php – Docblocks · Hooks
• bp-forums/bp-forums-template.php – Docblocks · Hooks
• bp-forums/deprecated/1.6.php – Docblocks · Hooks
• bp-forums/deprecated/1.7.php – Docblocks · Hooks
• bp-friends/bp-friends-actions.php – Docblocks · Hooks
• bp-friends/bp-friends-activity.php – Docblocks · Hooks
• bp-friends/bp-friends-cache.php – Docblocks · Hooks
• bp-friends/bp-friends-classes.php – Docblocks · Hooks
• bp-friends/bp-friends-filters.php – Docblocks · Hooks
• bp-friends/bp-friends-functions.php – Docblocks · Hooks
• bp-friends/bp-friends-loader.php – Docblocks · Hooks
• bp-friends/bp-friends-notifications.php – Docblocks · Hooks
• bp-friends/bp-friends-screens.php – Docblocks · Hooks
• bp-friends/bp-friends-template.php – Docblocks · Hooks
• bp-friends/bp-friends-widgets.php – Docblocks · Hooks
• bp-groups/bp-groups-actions.php – Docblocks · Hooks
• bp-groups/bp-groups-activity.php – Docblocks · Hooks
• bp-groups/bp-groups-admin.php – Docblocks · Hooks
• bp-groups/bp-groups-adminbar.php – Docblocks · Hooks
• bp-groups/bp-groups-buddybar.php – Docblocks · Hooks
• bp-groups/bp-groups-cache.php – Docblocks · Hooks
• bp-groups/bp-groups-classes.php – Docblocks · Hooks
• bp-groups/bp-groups-filters.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-groups/bp-groups-forums.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-groups/bp-groups-functions.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-groups/bp-groups-loader.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-groups/bp-groups-notifications.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-groups/bp-groups-screens.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-groups/bp-groups-template.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-groups/bp-groups-widgets.php – Docblocks · Hooks – in progress – @darrenmeehan
• bp-loader.php – Docblocks · Hooks
• bp-members/bp-members-actions.php – Docblocks · Hooks
• bp-members/bp-members-adminbar.php – Docblocks · Hooks
• bp-members/bp-members-buddybar.php – Docblocks · Hooks
• bp-members/bp-members-filters.php – Docblocks · Hooks
• bp-members/bp-members-functions.php – Docblocks · Hooks
• bp-members/bp-members-loader.php – Docblocks · Hooks
• bp-members/bp-members-notifications.php – Docblocks · Hooks
• bp-members/bp-members-screens.php – Docblocks · Hooks
• bp-members/bp-members-template.php – Docblocks · Hooks
• bp-messages/bp-messages-actions.php – Docblocks · Hooks
• bp-messages/bp-messages-cache.php – Docblocks · Hooks
• bp-messages/bp-messages-classes.php – Docblocks · Hooks
• bp-messages/bp-messages-cssjs.php – Docblocks · Hooks
• bp-messages/bp-messages-filters.php – Docblocks · Hooks
• bp-messages/bp-messages-functions.php – Docblocks · Hooks
• bp-messages/bp-messages-loader.php – Docblocks · Hooks
• bp-messages/bp-messages-notifications.php – Docblocks · Hooks
• bp-messages/bp-messages-screens.php – Docblocks · Hooks
• bp-messages/bp-messages-template.php – Docblocks · Hooks
• bp-messages/bp-messages-widgets.php – Docblocks · Hooks
• bp-notifications/bp-notifications-actions.php – Docblocks · Hooks
• bp-notifications/bp-notifications-adminbar.php – Docblocks · Hooks
• bp-notifications/bp-notifications-buddybar.php – Docblocks · Hooks
• bp-notifications/bp-notifications-classes.php – Docblocks · Hooks
• bp-notifications/bp-notifications-functions.php – Docblocks · Hooks
• bp-notifications/bp-notifications-loader.php – Docblocks · Hooks
• bp-notifications/bp-notifications-screens.php – Docblocks · Hooks
• bp-notifications/bp-notifications-template.php – Docblocks · Hooks
• bp-settings/bp-settings-actions.php – Docblocks · Hooks
• bp-settings/bp-settings-functions.php – Docblocks · Hooks
• bp-settings/bp-settings-loader.php – Docblocks · Hooks
• bp-settings/bp-settings-screens.php – Docblocks · Hooks
• bp-settings/bp-settings-template.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress-functions.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/activity/activity-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/activity/comment.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/activity/entry.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/activity/index.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/activity/post-form.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/activity/single/home.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/blogs/blogs-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/blogs/create.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/blogs/index.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/forums/forums-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/forums/index.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/create.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/groups-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/index.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/activity.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/admin.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/forum.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/forum/edit.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/forum/topic.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/group-header.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/home.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/members.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/plugins.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/request-membership.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/groups/single/send-invites.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/activate.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/index.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/members-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/register.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/activity.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/blogs.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/forums.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/forums/topics.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/friends.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/friends/requests.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/groups.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/groups/invites.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/home.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/member-header.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/messages.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/messages/compose.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/messages/messages-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/messages/notices-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/messages/single.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/notifications.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/notifications/feedback-no-notifications.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/notifications/notifications-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/notifications/read.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/notifications/unread.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/plugins.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/profile.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/profile/change-avatar.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/profile/edit.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/profile/profile-loop.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/profile/profile-wp.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/settings.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/settings/capabilities.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/settings/delete-account.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/settings/general.php – Docblocks · Hooks
• bp-templates/bp-legacy/buddypress/members/single/settings/notifications.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-actions.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-activity.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-admin.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-buddybar.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-cache.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-caps.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-classes.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-cssjs.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-filters.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-functions.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-loader.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-screens.php – Docblocks · Hooks
• bp-xprofile/bp-xprofile-template.php – Docblocks · Hooks

#5022