Skip to:
Content

BuddyPress.org

Opened 14 years ago

Closed 11 years ago

Last modified 8 years ago

#2345 closed enhancement (fixed)

PHP documentation needed through-out BP

Reported by: johnjamesjacoby's profile johnjamesjacoby Owned by: cnorris23's profile cnorris23
Milestone: 1.5 Priority: minor
Severity: normal Version:
Component: Core Keywords:
Cc: Backie

Description

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

Attachments (7)

2345a.diff (7.1 KB) - added by Backie 13 years ago.
BP_Core_User
2345b.diff (5.7 KB) - added by Backie 13 years ago.
BP_Core_Notification
2345c.diff (1.6 KB) - added by Backie 13 years ago.
BP_Button
2345d.diff (3.4 KB) - added by Backie 13 years ago.
bp-core-avatars.php
2345.001.diff (112.0 KB) - added by cnorris23 13 years ago.
bp-activity folder
2345.002.diff (56.0 KB) - added by cnorris23 13 years ago.
bp-blogs folder
2345.blogs.003.diff (55.9 KB) - added by cnorris23 13 years ago.
bp-blogs folder with updated subpackage

Download all attachments as: .zip

Change History (29)

#1 @johnjamesjacoby
14 years ago

  • Keywords gcin needs-patch added
  • Priority changed from normal to major
  • Type changed from enhancement to task

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

#2 @johnjamesjacoby
13 years ago

  • Keywords gcin removed
  • Owner johnjamesjacoby deleted
  • Status changed from new to assigned

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

#3 @DJPaul
13 years ago

  • Milestone changed from 1.3 to Future Release

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

#4 @Backie
13 years ago

  • Cc Backie added

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.

#5 @Backie
13 years ago

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
13 years ago

BP_Core_User

@Backie
13 years ago

BP_Core_Notification

@Backie
13 years ago

BP_Button

@Backie
13 years ago

bp-core-avatars.php

#6 @DJPaul
13 years ago

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

#7 @DJPaul
13 years ago

  • Milestone changed from Future Release to 1.3
  • Priority changed from major to normal

#8 @DJPaul
13 years ago

  • Priority changed from normal to minor

#9 @djpaul
13 years ago

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

#10 @DJPaul
13 years ago

  • Milestone changed from 1.3 to Future Release

@cnorris23
13 years ago

bp-activity folder

#11 @cnorris23
13 years ago

  • Keywords has-patch added; needs-patch removed
  • Severity set to normal

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.

#12 @boonebgorges
13 years ago

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

@cnorris23
13 years ago

bp-blogs folder

#13 @cnorris23
13 years ago

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.

#14 @DJPaul
13 years ago

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!

`

`

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

#15 @cnorris23
13 years ago

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,

or to use underscores

#16 @boonebgorges
13 years ago

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.

#17 @cnorris23
13 years ago

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

#18 @cnorris23
13 years ago

  • Owner set to cnorris23

@cnorris23
13 years ago

bp-blogs folder with updated subpackage

#19 @cnorris23
13 years ago

Update Blogs component @subpackage to component name only

#20 @cnorris23
13 years ago

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.

#21 @DJPaul
11 years ago

  • Keywords has-patch removed
  • Milestone changed from Future Release to 1.5
  • Resolution set to fixed
  • Status changed from assigned to closed

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.

#22 @DJPaul
8 years ago

  • Type changed from task to enhancement
Note: See TracTickets for help on using tickets.