Need standard way to document the format of attributes in theme functions

Since one can assign multiple classes to a single item, this is by design. As you mention, the Form API also uses the same syntax:
$form['#attributes'] = array('class' => array('search-form'));

In d7, all attributes are arrays, not just 'class'. I don't think we should be singling out class in the doc. Rather we should point out the drupal_attributes() function, which is used to format the attributes.

Needs patch in d8 first, then backport to d7.

Subscribe - documentation needs some love. IMO we should be able to use both 'class' => 'single-class' as well as 'class' => array('single-class') but that's just me.

RE #6 - that change was made in Drupal 7 after much discussion... So this issue is about updating the documentation so that it makes the functions clearer.

Yup, understood that much. Sorry, probably not the right place to vent :)

Between the change already noted and #1317628: Clean up API docs for includes directory, files starting with N-Z can this issue be closed?

(corrected the issue number)

The suggested change in #5 is to point out that attributes are formatted with drupal_attributes(), which hasn't been done, and I don't see it in that other patch either?

I'm trying to figure out the best way to handle this.
Seven functions have attributes in the $variables array with most of them making a note that they are an array of some form. The obvious exception is theme_item_list(). Should I a) add @see drupal_attributes() to all of the docblocks or b) just reference it within the description for the attributes of theme_item_list which leaves the possibility that someone else will run into a similar problem.

Line 1568: * - attributes: (optional) An associative array of HTML attributes to apply
function theme_datetime($variables) {
Line 1664: * - attributes: (optional) Attributes for the anchor, or for the tag
Line 1669: * - attributes: A keyed array of attributes for the UL containing the
function theme_links($variables) {
Line 1789: * - attributes: Associative array of attributes to be placed in the img tag.
function theme_image($variables) {
Line 1863: * - attributes: An array of HTML attributes to apply to the table tag.
function theme_table($variables) {
Line 2087: * - attributes: The attributes applied to the list element.
function theme_item_list($variables) {
Line 2200: * - #attributes: (optional) An array of HTML attributes to apply to the
function theme_html_tag($variables) {
Line 2277: * - attributes: Associative array of attributes to be placed in the meter
function theme_meter($variables) {

Hmmm... Maybe they should all say:

An associative array of HTML attributes [specifics here, such as "for the anchor tag" etc.]. Attributes are formatted using drupal_attributes().

How's that for an idea?

Take a look at this and let me know what you think.

Looks good! The only thing I would change is that since we are referencing drupal_attributes(), I think we can take out sentences like this:

If element 'class' is included, it must be an array of one or more class names.

And is that really the complete list of theme functions that use attributes?
http://api.drupal.org/api/drupal/core!includes!common.inc/function/calls...
Wow... looks like there are quite a few... maybe we should reconsider whether we really need to add this sentence to all of them. How necessary is it? Is it common knowledge?

jhodgdon,

Slightly updated patch. In regards to the common knowledge I'm really not sure if it is or not. That seems to be the whole reason this issue was opened so I would lean towards saying no.

Agreed it is probably needed.. but if so, the patch probably needs to expand to encompass all or most of the 48 functions that call drupal_attributes.

And maybe we should change the wording to "Attributes are passed to drupal_attributes() for formatting." just to make it one bit clearer? I'm OK with either way, but I think this wording might make it abundantly clear that you need to supply attributes that that function can format properly.

As one more note, the whole thing of class needing to be an array and not a string is incorrect for drupal_attributes() itself. Some of the functions, however, add their own items to class, such as:
$attributes['class'][] = 'whatever'
So actually just saying that it is formatted with drupal_attributes() may not be sufficient... sigh.

:(

I'll take another stab at it, but if we are adding something to all 48 calls should we just add @see?

I think the documentation for it does a good job of explaining how to use it.

My only hesitation with adding the @see is that the actual use might be lost with all of the other variables listed for the functions.

We need to be consistent. Either we put it in all 48 (or at least those of the 48 where it's appropriate -- maybe not quite all), or we put it in none of them. I would actually vote for none.

Putting in @see is not going to help IMO, because the See Also section will be far away from the place where people aren't realizing they need to make the individual attributes arrays, and also as I noted above, actually drupal_attributes() doesn't care whether class is an array or a single value, it's just the individual functions that care because they're adding more elements to class.

So... with all this in mind, I am really inclined to call this a "won't fix".

I just marked #1418624: theme_table() [and other HTML element theme functions?] should document class attributes being an array as a duplicate of this one.

Tagging this one since we'll need to use a consistent way to document all our attributes in Twig templates too :)

Does this need to be done in D8?

There is no longer drupal_attributes(), it's now the Attribute class. Can this be bumped back down to D7?

This should be a D7 issue now. The docs are not clear about how to add a class to a <li> item, it just says "All other elements (besides "data" and "children") are treated as attributes of the list item element." This misleads to trying to add a class element as a string (which produces the fatal error), specially since any other element specified as as a string is correctly added as an attribute to the <li>.

Dropping back down to D7. D8 we are using Attribute class and doing things like