Inline docs for Twenty Ten

[nacin]

1) Document its functions.

2) Consider some PHP comments in various template files to explain certain things, as needed.

[westi]

(In [13816]) Switch to get_template_part Fixes #12371. Try on some narrative comments for size see #12695.

[jorbin]

first pass

[jorbin]

Added a first pass at documenting everything. The one I'm not very confident on is the long description of page.php . If someone else has a better idea for that I'm all ears.

[jorbin]

cleaned it up a bit

[jorbin]

.2 wasn't patching correctly. try this one.

[demetris]

My first pass on jorbin’s first pass (twentytendoc.3.diff)

[demetris]

Attached file with tweaks to jorbin’s first pass (twentytendoc.3.diff).

Main changes:

• Demoted 2010 to @subpackage and added @package WordPress. This is not because 2010 is bundled in the core distribution, but to allow references to core stuff via @uses, @see, etc.
• Added @since in the form X.Y.Z (to conform with core practice, where three levels are used).
• Added file-level phpDoc to index.php.

[jorbin]

Added some more inline docs to explain twentyten_init

[jorbin]

Added more inline documentation to twentyten_init with the goal of making understanding the easy of creating a child theme. Based on Demetris's tweaks to my first pass.

[nacin]

(In [13885]) Rough cut of Twenty Ten inline documentation. see #12695. props jorbin, demetris.

[nacin]

(In [13886]) Second pass on twentyten/functions.php inline documentation. see #12695. Also:

rename twentyten_init() to twentyten_setup(), to reflect the hook it is run on (init would be too late, it must be after_setup_theme). Remove unnecessary twentyten_get_page_number() and transfer functionality to twentyten_the_page_number(). Remove the function_exists() wrappers from functions that are simply tied to a hook, as a better practice would be to remove the hook instead of plugging the function. For architecture changes, see #12748.

[nacin]

(In [13888]) Clarify order of operations for a child theme removing a filter of a parent theme. see #12695, see #12748

[jorbin]

fix @subpackage, add @since for both WP and TT, general improvements

[jorbin]

I added a new patch that adjust @subpackage to Twenty_Ten based on the requirements from ​http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.subpackage.pkg.html

Also adds some more inline documentation and @since for both WordPress and Twenty Ten

[jacobsantos]

Hey thanks, I just hope this gets committed.

[dremeda]

inline doc change for archive.php in twentyten

[dremeda]

inline doc change for archive.php in twentyten

[dremeda]

sorry for the repeat comments here. last one was for search.php not archive.php

[nacin]

(In [14698]) Twenty Ten documentation and functions.php improvements. see #12695.

[michaelh]

probably meant to refer to Child Themes article here

[dremeda]

Various minor changes to Twenty Ten Docs

[nacin]

Going to commit a final big patch for this.

[nacin]

(In [14707]) Various minor tweaks to file-level phpdoc in Twentyten. props dremeda. see #12695.

[nacin]

(In [14708]) In Twenty Ten, documentation and code improvements. see #12695.

[nacin]

Last commit added explanatory and conversational inline documentation throughout the template files. It also made some other changes:

• Give attachment.php, page.php, onecolumn-page, etc. valid loops. Previously done for single.php: [14476].
• Switch @since to a Twenty Ten-specific version. Done previously for functions.php in [14698].
• Don't use the_post/rewind_posts hack in tag.php, we don't need it for single_tag_title.
• Remove erroneous argument to the_excerpt(). See also #13361, which I'll be taking up.

Closing as fixed. Re-open if I break something. Thanks everyone for your help.

[nacin]

(In [14709]) Refer to the right codex article. props MichaelH, see #12695.

[nacin]

Okay, looking through the patches in the ticket now to see if anything was missed. Sorry Aaron especially, I didn't see some of these (and independently made the @since and @subpackage calls today).

I see some good comments in some of these I want to add. I will go through these tomorrow.

[zeo]

Is there still any room for translators comment (i18n)?

[zeo]

Refresh patch. Corrected various end / closing comment. Extra: adds padding to class nopassword.

[jorbin]

Added a patch that makes sure every </div> that is not on the same line as the opening <div> is commented and other general improvements.

[nacin]

Reviewing this, will clean it up and check it in.

I personally hate the closing div comments in general, but I understand the need for them. That said, I purposely haven't added them (in fact I've removed them) when the content between them -- both in PHP, and what the PHP might generate in terms of markup -- is small. (If the_content() for example is between them, then I'd leave it in.)

[jorbin]

I'm not a huge fan of them, but I think it's important to be consistent and that some themers would find them useful, hence why I cleaned up / added the last of the remaining ones.

[nacin]

[14786]

[zeo]

used #post-## for comments

[nacin]

(In [14932]) Use a more generic HTML comment. props zeo, fixes #12695.

[nacin]

Thanks zeo, I missed those when massaging previous patches.