WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 7 years ago

#21303 closed enhancement (fixed)

class-wp-customize-*.php files inline documentation

Reported by: bananastalktome Owned by:
Milestone: 3.5 Priority: normal
Severity: trivial Version:
Component: Inline Docs Keywords: has-patch
Focuses: Cc:
PR Number:

Description

I took a first pass at the inline documentation for the WP_Customize_Control class. I am not sure whether this sort of patch is helpful or not, so I will wait for feedback before I potentially take on additional classes.

Thanks!

Attachments (3)

diff.patch (2.9 KB) - added by bananastalktome 7 years ago.
Updated tabs
diff2.patch (9.9 KB) - added by bananastalktome 7 years ago.
diff3.patch (19.5 KB) - added by bananastalktome 7 years ago.
Includes inline docs (or stubs) for all 4 class-wp-customize-*.php files

Download all attachments as: .zip

Change History (12)

#1 @ocean90
7 years ago

  • Keywords 2nd-opinion removed
  • Milestone changed from Awaiting Review to 3.5

Seems like you are using whitespaces to indent? Core does use tabs to indent lines.

Also inline docs are always good.

@bananastalktome
7 years ago

Updated tabs

#2 @bananastalktome
7 years ago

@ocean90 could have sworn I changed Coda to tabs, fixed in new patch

#3 @bananastalktome
7 years ago

New diff to include inline docs for whole file, not just WP_Customize_Control

@bananastalktome
7 years ago

Includes inline docs (or stubs) for all 4 class-wp-customize-*.php files

#4 @bananastalktome
7 years ago

  • Summary changed from First pass at WP_Customize_Control class inline documentation to WP_Customize_* class inline documentation

#5 @bananastalktome
7 years ago

  • Summary changed from WP_Customize_* class inline documentation to class-wp-customize-*.php files inline documentation

#6 @ryan
7 years ago

In [21354]:

phpdoc for Customizer classes and methods. Props bananastalktome. see #21303

#7 follow-up: @scribu
7 years ago

Are @access keywords really necessary when there's an explicit keyword present in the code?

#8 in reply to: ↑ 7 @nacin
7 years ago

Replying to scribu:

Are @access keywords really necessary when there's an explicit keyword present in the code?

Good question. I don't see them documented anywhere on the phpdoc 2 site. I do know that @access private prevents documentation from being generated (unless a flag is set on generation), which is very helpful for hiding our many internal functions from phpdoc output. But it's definitely possible that it was removed on the basis of PHP5 visibility keywords.

That said, we should still use them especially in our pre-3.2 classes, where we might have a "private" variable or function that, for compatibility reasons, we can't mark with a visibility keyword. In these cases, I have avoided marking these functions as explicitly "public," and I've left should-be variables as "var".

#9 @nacin
7 years ago

  • Resolution set to fixed
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.