#348907 follow-up: _privatemsg_list_thread() documentation corrections [#429734]

In privatemsg.module the _privatemsg_list_thread() function has this documentation:

/**
 * Formats a row in the message list.
 *
 * Does use theme patterns to display the single fields.
 * 
 * @param $thread
 *   Array with the row data returned by the database.
 * @return
 *   Row definition for use with theme('table')
 */

This:

* Does use theme patterns to display the single fields.

Should probably read:

* Uses patterns to theme single fields according to their type.

Assuming I have interpreted what theme patterns are for correctly. :)

Comment	File	Size	Author
#6	privatemsg.pattern_link.patch	1.07 KB	berdir
#4	429734.apidoc.patch	681 bytes	liam mcdermott

Comments

Comment #2

berdir

German

Switzerland

commented 10 April 2009 at 19:40

Hm. I'm not a native speaker, but your suggestion doesn't make sense to me. "theme pattern" imho belongs together, it's a feature that the theme system provides.

A "theme pattern" is simply a wildcard for theme names. By defining "'pattern' => 'privatemsg_list_header__',", the theme system will search for functions that start with that name (and with the theme name prefix). We can then pass an array with multiple possible names to theme() which will use the first match it can find. That's basically everything these patterns do.

I will handle the documentation of those that in a separate topic in the apidocs.

Comment #3

liam mcdermott commented 16 April 2009 at 17:38

Fair enough, the problem with the existing docs are 'Does use' should be 'Uses' and 'display the single fields' should be 'display single fields'. :)

So, how about:

* Uses theme patterns to theme single fields.

I understand how theme patterns work. What I don't understand is what problem they solve. If we can explain -- in the docs -- the problem we're solving, and how theme patterns solve that problem, it becomes obvious why the code is the way it is.

Comment #4

liam mcdermott commented 17 April 2009 at 19:31

Component:	Code	» Documentation
Status:	Active	» Needs review

Status	File	Size
new	429734.apidoc.patch	681 bytes

And here's a patch.

Comment #5

litwol commented 8 June 2009 at 11:31

Commited the patch from #4 as is. however it is not immediately clera what are those evil patterns. To help whomever is reading this line of code find more information we should include some further reading link. Not sure if @see is able to point to files which documents this well (privatemsg.theme.inc), if not then we can just point the reader to documentation on d.o if such exists.