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.

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

first pass

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.

cleaned it up a bit

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

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

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.

Added some more inline docs to explain twentyten_init

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.

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

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

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

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

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

Hey thanks, I just hope this gets committed.

inline doc change for archive.php in twentyten

inline doc change for archive.php in twentyten

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

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

probably meant to refer to Child Themes article here

Various minor changes to Twenty Ten Docs

Going to commit a final big patch for this.

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

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

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.

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

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.

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

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

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.

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

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.

[14786]

used #post-## for comments

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

Thanks zeo, I missed those when massaging previous patches.