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

[bananastalktome]

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!

[ocean90]

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

Also inline docs are always good.

[bananastalktome]

Updated tabs

[bananastalktome]

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

[bananastalktome]

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

[bananastalktome]

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

[ryan]

In [21354]:

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

[scribu]

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

[nacin]

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".