WordPress.org

Make WordPress Core

Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#12695 closed task (blessed) (fixed)

Inline docs for Twenty Ten

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

Description

1) Document its functions.

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

Attachments (13)

twentytendoc.diff (16.5 KB) - added by jorbin 10 years ago.
first pass
twentytendoc.2.diff (16.4 KB) - added by jorbin 10 years ago.
cleaned it up a bit
twentytendoc.3.diff (15.8 KB) - added by jorbin 10 years ago.
.2 wasn't patching correctly. try this one.
twentytendoc.4.demetris.diff (18.1 KB) - added by demetris 10 years ago.
My first pass on jorbin’s first pass (twentytendoc.3.diff)
twentytendoc.4.diff (19.0 KB) - added by jorbin 10 years ago.
Added some more inline docs to explain twentyten_init
twenty_ten_docs.diff (19.2 KB) - added by jorbin 10 years ago.
fix @subpackage, add @since for both WP and TT, general improvements
archive.php.diff (512 bytes) - added by dremeda 10 years ago.
inline doc change for archive.php in twentyten
search.php.diff (394 bytes) - added by dremeda 10 years ago.
inline doc change for archive.php in twentyten
12695.diff (860 bytes) - added by michaelh 10 years ago.
probably meant to refer to Child Themes article here
2010-docs.diff (7.1 KB) - added by dremeda 10 years ago.
Various minor changes to Twenty Ten Docs
12695-comment.diff (7.8 KB) - added by zeo 10 years ago.
Refresh patch. Corrected various end / closing comment. Extra: adds padding to class nopassword.
14750.diff (19.1 KB) - added by jorbin 10 years ago.
post-id-comments.diff (2.5 KB) - added by zeo 10 years ago.
used #post-## for comments

Download all attachments as: .zip

Change History (40)

#1 @demetris
10 years ago

  • Cc dkikizas@… added

#2 @westi
10 years ago

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

@jorbin
10 years ago

first pass

#3 @jorbin
10 years ago

  • Cc aaron@… added
  • Keywords has-patch added; needs-patch removed

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
10 years ago

cleaned it up a bit

@jorbin
10 years ago

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

@demetris
10 years ago

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

#4 @demetris
10 years ago

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
10 years ago

Added some more inline docs to explain twentyten_init

#5 @jorbin
10 years ago

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.

#6 @nacin
10 years ago

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

#7 @nacin
10 years ago

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

#8 @nacin
10 years ago

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

@jorbin
10 years ago

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

#9 @jorbin
10 years ago

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

#10 @jacobsantos
10 years ago

Hey thanks, I just hope this gets committed.

#11 @dremeda
10 years ago

  • Cc dre@… added

@dremeda
10 years ago

inline doc change for archive.php in twentyten

@dremeda
10 years ago

inline doc change for archive.php in twentyten

#12 @dremeda
10 years ago

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

#13 @nacin
10 years ago

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

@michaelh
10 years ago

probably meant to refer to Child Themes article here

@dremeda
10 years ago

Various minor changes to Twenty Ten Docs

#14 @nacin
10 years ago

  • Status changed from new to accepted

Going to commit a final big patch for this.

#15 @nacin
10 years ago

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

#16 @nacin
10 years ago

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

#17 @nacin
10 years ago

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.

#18 @nacin
10 years ago

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

#19 @nacin
10 years ago

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.

#20 @zeo
10 years ago

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

@zeo
10 years ago

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

@jorbin
10 years ago

#21 @jorbin
10 years ago

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.

#22 @nacin
10 years ago

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

#23 @jorbin
10 years ago

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.

#24 @nacin
10 years ago

  • Resolution set to fixed
  • Status changed from accepted to closed

@zeo
10 years ago

used #post-## for comments

#25 @zeo
10 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

#26 @nacin
10 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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

#27 @nacin
10 years ago

Thanks zeo, I missed those when massaging previous patches.

Note: See TracTickets for help on using tickets.