API page: http://api.drupal.org/api/drupal/modules--block--block.module/function/b...

In the page there are some HTML tags that appear as plain text.

> @todo Now that the blocks table has a primary key, we should use that as the array key instead of

<i>module</i>_<i>delta</i><code>.

> An array of block objects, indexed with <code><i>module</i>_<i>delta</i>

.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

apaderno’s picture

Version: 6.x-dev » 7.x-dev

The issue is present in the documentation pages for Drupal 7 and Drupal 6.

jhodgdon’s picture

Title: HTML tags are rendered as plain text in the documentation for block_list() » HTML tags in the documentation for block_list() (shouldn't be)
Version: 7.x-dev » 8.x-dev
Issue tags: +Needs backport to D6, +Novice, +Needs backport to D7

The HTML tags should not be there. Please patch 8.x/7.x first, then backport to 6.x. Good project for a novice doc contributor!

barbi’s picture

Assigned: Unassigned » barbi
Status: Active » Needs review
FileSize
843 bytes

Removed the HTML tags.
I assumed the word is module_delta.

joachim’s picture

Status: Needs review » Needs work

The intent of the <i> tags was to show that the words module and delta are merely placeholders. That's not as clear with the changes in the patch -- I mean I would hope nobody would think the array is keyed with the literal string 'module_delta' all the way as that would be silly, but still, it's less clear.

When using placeholders in issue comments or documentation I tend to write in caps, so MODULE_DELTA, but I don't know if this is standard in core, or whether that's sufficiently clear as being two things stuck together.

I'd suggest maybe $module_$delta, or maybe explicitly stating what we're doing, like this:

* An array of block objects, indexed with the module name and block delta concatenated with an underscore, thus: $module_$delta.

Or... more simply, is there doxygen markup for emphasis?

jhodgdon’s picture

All caps is the standard way in doc to indicate a placeholder, for better or for worse, so let's go with that.

Also, in the patch -- when you remove the i tags, you need to fix the word wrapping so that the lines wrap to as close to 80 characters as possible. Thanks!

joachim’s picture

> All caps is the standard way in doc to indicate a placeholder, for better or for worse, so let's go with that.

Ok. I would like to see some textual explanation too though, so it's clear that it's two placeholders not one.

oriol_e9g’s picture

Status: Needs work » Needs review
FileSize
1.06 KB

maybe this?

oriol_e9g’s picture

Assigned: barbi » oriol_e9g
joachim’s picture

Status: Needs review » Reviewed & tested by the community

Yup, that's spot on :)

jhodgdon’s picture

Looks good to me too, thanks! Please 8.x/7.x, and then mark to be ported for d6.

webchick’s picture

Version: 8.x-dev » 6.x-dev
Issue tags: -Needs backport to D7

Yeah, MODULE_DELTA isn't great, but it is how we do similar stuff elsewhere (e.g. hook_form_FORM_ID_alter()). So this looks good.

Committed to 8.x and 7.x. Thanks! Marking back for 6.x. Seems to apply with fuzz.

joachim’s picture

> hook_form_FORM_ID_alter

Heh, that actually means that's wrong -- it should be FORMID, if _ indicates a separation between pseudotokens...

jhodgdon’s picture

Status: Reviewed & tested by the community » Patch (to be ported)

We probably should port the patch just in case...

cashwilliams’s picture

Status: Patch (to be ported) » Needs review
FileSize
1.06 KB

patch for 6.x

jhodgdon’s picture

Status: Needs review » Needs work

Thanks! Small typo: should be MODULE_DELTA not MODULE_DETA.

oriol_e9g’s picture

Assigned: oriol_e9g » Unassigned
aenw’s picture

Status: Needs work » Needs review
FileSize
1.06 KB

fixed typo

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Looks good now, thanks!

Gábor Hojtsy’s picture

Status: Reviewed & tested by the community » Fixed

Thanks, committed, pushed.

Automatically closed -- issue fixed for 2 weeks with no activity.