Skip to:
Content

Opened 9 years ago

Closed 6 years ago

Last modified 3 years ago

#2345 closed enhancement (fixed)

PHP documentation needed through-out BP

Reported by: johnjamesjacoby Owned by: 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 8 years ago.
BP_Core_User
2345b.diff (5.7 KB) - added by Backie 8 years ago.
BP_Core_Notification
2345c.diff (1.6 KB) - added by Backie 8 years ago.
BP_Button
2345d.diff (3.4 KB) - added by Backie 8 years ago.
bp-core-avatars.php
2345.001.diff (112.0 KB) - added by cnorris23 8 years ago.
bp-activity folder
2345.002.diff (56.0 KB) - added by cnorris23 8 years ago.
bp-blogs folder
2345.blogs.003.diff (55.9 KB) - added by cnorris23 7 years ago.
bp-blogs folder with updated subpackage

Download all attachments as: .zip

Change History (29)

#1 @johnjamesjacoby
8 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
8 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
8 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
8 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
8 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
8 years ago

BP_Core_User

@Backie
8 years ago

BP_Core_Notification

@Backie
8 years ago

BP_Button

@Backie
8 years ago

bp-core-avatars.php

#6 @DJPaul
8 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
8 years ago

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

#8 @DJPaul
8 years ago

  • Priority changed from normal to minor

#9 @djpaul
8 years ago

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

#10 @DJPaul
8 years ago

  • Milestone changed from 1.3 to Future Release

@cnorris23
8 years ago

bp-activity folder

#11 @cnorris23
8 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
8 years ago

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

@cnorris23
8 years ago

bp-blogs folder

#13 @cnorris23
8 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
8 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
8 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
8 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
8 years ago

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

#18 @cnorris23
7 years ago

  • Owner set to cnorris23

@cnorris23
7 years ago

bp-blogs folder with updated subpackage

#19 @cnorris23
7 years ago

Update Blogs component @subpackage to component name only

#20 @cnorris23
7 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
6 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
3 years ago

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