[development] Templatizing Drupal's Themes: Documentation Proposal

[Earl Miles]

In an effort to convert as much of Drupal's theme_* functions to tpl.php files 
as possible, I went through and did the forum module's theme functions (I 
picked those because I knew they'd be more difficult than some other modules).

One thing I encountered is that this new system has no documentation standard 
for tpl.php files.

I propose the following items:

We should create a themes.php in contributions/docs/developer that contains
definitions for theme_* functions that are being converted (or are new and will
never have had a theme_* function before). Everything in this file should be 
@ingroup themeable. It would contain the full documentation for the theme
function, including the @params.

All .tpl.php files should contain a Doxy syntax @file directive that summarizes 
the template and lists variables that are commonly available. This list does 
not need to be exhaustive but it should include the most important variables, 
at a minimum. It should contain an @see to the template_preprocess function, if 
it exists, and a @see to the theme_HOOK function in the contrib docs.

The template_preprocess_HOOK function should contain a @see to the theme_ 
function and a list of the arguments (mostly for reference while looking at the 
function; since the argument to that function will always just be &$variables, 
it's nice to get a look at what data is coming in).

Both of the above should also contain an @see to the .tpl.php file -- however, 
in api.module, currently @see doesn't work on files. I think api.module could 
probably be modified to rectify this for us, or another method of referencing 
the file could work.

Here are some examples. Note that I did these before I thought about a 
theme.php so these aren't updated for that yet, but I intend to.

forum_list.tpl.php:
<?php // $Id$
/**
  * @file forum_list.tpl.php
  * Default theme implementation to display a list of forums.
  *
  * Available variables:
  * - $forums: An array of forums to display.
  *
  * Each $forum in $forums contains:
  * - $forum->is_container: Is TRUE if the forum can contain other forums. Is
  *   FALSE if the forum can contain only topics.
  * - $forum->depth: How deep the forum is in the current hierarchy.
  * - $forum->name: The name of the forum.
  * - $forum->link: The URL to link to this forum.
  * - $forum->description: The description of this forum.
  * - $forum->new_topics: True if the forum contains unread posts.
  * - $forum->new_url: A URL to the forum's unread posts.
  * - $forum->new_text: Text for the above URL which tells how many new posts.
  * - $forum->old_topics: A count of posts that have already been read.
  * - $forum->num_posts: The total number of posts in the forum.
  * - $forum->last_reply: Text representing the last time a forum was posted or
  *   commented in.
  *
  * @see template_preprocess_forum_list()
  */
?>

Example in api.module: 
http://drupal.logrus.com/api/file/drupal/modules/forum/forum_list.tpl.php/head

/**
  * Process variables for forum_display.tpl.php
  *
  * The $variables array contains the following arguments:
  * - $forums
  * - $topics
  * - $parents
  * - $tid
  * - $sortby
  * - $forum_per_page
  *
  * @see forum_display.tpl.php
  */
function template_preprocess_forum_display(&$variables) {

Example in api.module: 
http://drupal.logrus.com/api/function/template_preprocess_forum_list/head