Add docblocks to Thematic: A first pass

[GoogleCodeExporter]

Let the documentation begin

Original issue reported on code.google.com by eugene.m...@gmail.com on 17 Jan 2012 at 3:31

[GoogleCodeExporter]

sample override block:

// If override is defined thematic_* function is a wrapper for the childtheme's 
override 
if (function_exists('childtheme_override_postfooter'))  {
    /**
     * @ignore
     */
    function thematic_postfooter() {
        childtheme_override_postfooter();
    }
} else {
    /**
     * [Short Desc]
     *
     * [Long Desc]
     *
     * @[tags]
     */
    function thematic_postfooter() {

Original comment by eugene.m...@gmail.com on 17 Jan 2012 at 3:42

[GoogleCodeExporter]

Package structure:

Thematic
--Templates
--ThemeInit
ThematicCoreLibrary
--Extensions (breakout into individual extensions subs)
ThematicLegacy
ThematicSampleChildTheme
--ThemeInit

Original comment by eugene.m...@gmail.com on 17 Jan 2012 at 3:45

[GoogleCodeExporter]

Typical page level block for a template

/**
* Short Description (Template Name)
*
* Long Description
*
* @package Thematic
* @subpackage Templates
*
* @link link-location link-title
*@since (if anyone wants to dig back through the releases)
*/

Original comment by eugene.m...@gmail.com on 17 Jan 2012 at 3:47

[GoogleCodeExporter]

For typical function level blocks for  functions that are obviously  Actions 
and Filters

    /**
     * [Short Desc] Filter: (if function is mostly a wrapper for a filter) or Action Hook: (if is wrapper for action
     *
     * [Long Desc] more detailed description
     *
     * @[tags]

     */

Original comment by eugene.m...@gmail.com on 17 Jan 2012 at 3:59

[GoogleCodeExporter]

Great start.

This is a partial content-extensions.php. I added documentation for the hooks 
in the beginning, the loops and thematic_content() and thematic_header() just 
to see how the cross-referencing worked. Just saw what you wrote above, but 
great minds think alike :) I have done almost exactly that. 

The question is how much use we will make of the cross-referencing. For 
example, if we tag every thematic function in the template files with @uses, 
there will no longer be strictly necessary to have "Located in xxx" in any 
comments since phpDocumentor keeps track of that. BUT to tag every single 
function in the templates as well is quite an undertaking and I wonder how 
useful it is in the end. I think it might help in the extensions files though, 
as phpDocumentor shows quite neatly how things are put together.

If you don't have any big reservations, I'll continue with the rest of the file.

Original comment by invistr...@gmail.com on 17 Jan 2012 at 5:20

Attachments:

• content-extensions.diff

[GoogleCodeExporter]

Roll w/ it. I like the more verbose short description you have used there: 
"Registers action hook"  instead of "Action Hook" move foreword with that 
change for sure.  "The located in".. long description is fine too. Its helpful 
to people when simply scanning the file.

In terms of cross referencing, it'd be great to see the functionality that 
@uses brings inside the documenter *but* it gonna make for giganto blocks. I 
even tried inline {@link element()} to test but it's still looks ugly. Lets 
skip it for now. 

I think the Package and Subpackage structure does a lot to help us navigate. 
Maybe we could revisit @uses for out of Package function references  at a later 
date.

Short Term Goals:
I'd like to see basic function lvl blocks across the board before going to 
review even if they only give a short descriptions based on existing inline 
comments.

Later Term Goals:
A revisited look at the package and subpackage structure.
A second pass with better descriptions & links for documentation Themeshaper 
&/or Thematic Theme.com (when that launches)
Research and add @since's for older functions.

I'm waiting on word from Ian & or Chris about various things. Currently they 
are the only ones who can submit for review. Once it gets submitted then 
there's the review

Post here to let me know what files you're currently working on so we don't 
repeat efforts. I'll do the same. I'm currently taking a break from it. My 
eye's have been bleeding from over-documantation lol. 

Original comment by eugene.m...@gmail.com on 17 Jan 2012 at 6:12

[GoogleCodeExporter]

Cool, I get going then.

Yeah it felt the blocks become very repetitive. I'll focus on just getting the 
docblocks going, mainly moving existing inline comments to the blocks and 
elaborating where it seems most urgent.

So I'll continue with content-extensions and then go for discussion-extensions 
and discussion.php. You take a break. Before we finish with this, I think we 
will both suffer from documentation overload. :-)

Original comment by invistr...@gmail.com on 17 Jan 2012 at 6:27

[GoogleCodeExporter]

Docblocked content-extensions.php

I found two functions that missed the thematic namespacing. Added @todos for 
them for the moment since I want to concentrate on one thing at a time. 

Original comment by invistr...@gmail.com on 18 Jan 2012 at 5:34

Attachments:

• -content-extensions.diff

[GoogleCodeExporter]

Docblocked discussion-extensions.php and discussion.php

If Kathy's looking over the dynamic classes, I'll wait with that. I'll continue 
with footer and header extensions. 

Original comment by invistr...@gmail.com on 18 Jan 2012 at 8:16

Attachments:

• -discussion-extensions.diff
• -discussion.diff

[GoogleCodeExporter]

Content-ext got committed with a few minor changes. Thanks!

Original comment by eugene.m...@gmail.com on 18 Jan 2012 at 8:19

[GoogleCodeExporter]

Added docblocks to footer-extensions and header-extensions.

Found another function that needed namespacing. And both the stylesheet and the 
comment-reply script ought to be put on hooks instead of echoed directly into 
the header (even though the style.css is optional, I would prefer it for 
consistency). Added @todos for that.

Will take a breather from this, and then tackle sidebar-extensions and 
widget-extensions.

Original comment by invistr...@gmail.com on 19 Jan 2012 at 12:43

Attachments:

• -footer-extensions.diff
• -header-extensions.diff

[GoogleCodeExporter]

Check out: http://phpdoc.thematictheme.com/ it's synced daily to trunk. Not 
sure that'll be permanent but for now it's there.

Original comment by eugene.m...@gmail.com on 20 Jan 2012 at 5:05

[GoogleCodeExporter]

I'm working on widgets-extensions.

Original comment by eugene.m...@gmail.com on 20 Jan 2012 at 9:45

[GoogleCodeExporter]

I've got helpers.php too

Original comment by eugene.m...@gmail.com on 21 Jan 2012 at 4:40

[GoogleCodeExporter]

Docblocks started in widget-ext r797 footer, header,discussion,discussion-ect 
in r798

Original comment by eugene.m...@gmail.com on 22 Jan 2012 at 8:47

[GoogleCodeExporter]

Original comment by eugene.m...@gmail.com on 23 Jan 2012 at 12:49

• Added labels: Documentation

[GoogleCodeExporter]

as per my checklist at <a 
href="http://code.google.com/p/thematic/issues/detail?id=126">issue 126</a> i 
think there are a lot of functions that need thematic_ namespacing.  

nice job w/ docu guys.  

i don't know if i mind printing the stylesheet directly in the header via 
wp_print_styles('thematic_style');  doesn't it give more control over where 
style.css appears?  ie... style.css appears before any other stylesheet.  does 
that even matter?  idk.  

if we're simply enqueing then, yeah we can just enqueue is on 
wp_enqueue_scripts hook and remove thematic_create_stylesheet() from the 
header.  also, is it necessary to register and then enqueue... you can load the 
source directly in the enqueue function

Original comment by helgathe...@gmail.com on 25 Jan 2012 at 12:35

[GoogleCodeExporter]

Added dockblocks for sidebar-extensions

Don't know if you wanted to keep the indentation/grouping of the hooks (main, 
index etc). I kept them for now.

I really like the move to using template files for the sidebars. But I found an 
elephant on the room: we are missing the subsidiaries! I only saw it because I 
was working on this file. I added comments based on my understanding and 
assumption of how this sidebar-subsidiary.php will look.

Can one make patches that add files?

Original comment by invistr...@gmail.com on 25 Jan 2012 at 9:36

Attachments:

• -sidebar-extensions.diff

[GoogleCodeExporter]

And regarding enqueing the stylesheet:

I know this gives more control to plugins. I think for example WP-minify works 
on all enqueued stylesheets, if we print them straight in header then the main 
thematic stylesheet would be inaccessible for it to minify. And by using 
enqueue, child themes can remove it with dequeue if they want (though in our 
case they would probably want to keep it).

And my understanding was also that you could simply enqueue in one go when you 
include the source. No need for registering then.

Original comment by invistr...@gmail.com on 25 Jan 2012 at 9:44

[GoogleCodeExporter]

i agree it should be enqueued.  but if you use wp_print_stylesheets() i'm 
relatively certain it won't print anything if you deregister the stylesheet and 
it should get wrapped up by minification plugins.  i'm not sure that wp-minify 
works on enqueued sheets or not, i thought that was why i switched to better 
wordpress minify.  i should test both assumptions.  

Original comment by helgathe...@gmail.com on 25 Jan 2012 at 1:09

[GoogleCodeExporter]

I'll go through sidebar-ext tonight EST.

We should start new tickets for both for namespacing and enqueuing 
conversations.

Also need to figure out where we are with the docs... what's begun and whats 
left for the "first pass" phase

Original comment by eugene.m...@gmail.com on 26 Jan 2012 at 5:37

[GoogleCodeExporter]

i think i already submitted a patch for enqueing the stylesheet.  it was in the 
theme checklist thread.  but at some point i will try to create some new 
tickets for all the different issues.  while that will blow up our number of 
issues it will also let us keep track of when they get resolved.  

Original comment by helgathe...@gmail.com on 26 Jan 2012 at 7:31

[GoogleCodeExporter]

stylesheet now enqueued in  r817 subsidiary actions restored in r819

shortcode.php documented

Original comment by eugene.m...@gmail.com on 30 Jan 2012 at 4:29

[GoogleCodeExporter]

I think all we have left for the initial pass at documenting the code are:

    helpers.php
    dynamic-classes.php

The templates need some explanations to remove the ...
@sinces for anyone who wants to do some archival research in the revision 
history

Am I missing anything else?

Original comment by eugene.m...@gmail.com on 16 Feb 2012 at 10:31

[GoogleCodeExporter]

The first few functions in widgets.php? And I think there's an extra docblock 
in functions.php from ye olde init.php?

Otherwise, I think those are the last remaining. To think that every single 
file has received some TLC, that's quite something. I have read code in places 
I never would have looked at otherwise, and really gotten to know Thematic 
under the hood. Tremendous learning experience.

So what do you plan to do with dynamic classes, just document it the way it is 
now and change to add_theme_support in the next version, or go for changing the 
body class filtering already now?

Original comment by invistr...@gmail.com on 16 Feb 2012 at 11:02

[GoogleCodeExporter]

Ok in r842 I basically wrapped up the first pass. Somewhat sloppy but I think 
we need to retire this ticket and look to a second pass in the future.

It's been an eye opener to me as well. Thank you so much for helping out. It's 
truly appreciated.

Body classes... YTBD

Original comment by eugene.m...@gmail.com on 17 Feb 2012 at 2:04

• Changed title: Add docblocks to Thematic: A first pass
• Changed state: Fixed

[GoogleCodeExporter]

very impressive work you two.  sorry i couldn't be more useful to the docblock 
effort. 

Original comment by helgathe...@gmail.com on 17 Feb 2012 at 3:54