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>
.
Files: 
CommentFileSizeAuthor
#17 blockModuleDocs-1175614-17.patch1.06 KBaenw
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]
#14 blockModuleDocs-1175614-14.patch1.06 KBCashWilliams
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]
#7 block_module_doc-1175614-7.patch1.06 KBoriol_e9g
PASSED: [[SimpleTest]]: [MySQL] 31,429 pass(es).
[ View ]
#3 block_module_doc-1175614-3.patch843 bytesbarbi
PASSED: [[SimpleTest]]: [MySQL] 29,898 pass(es).
[ View ]

Comments

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

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

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!

Assigned:Unassigned» barbi
Status:Active» Needs review
StatusFileSize
new843 bytes
PASSED: [[SimpleTest]]: [MySQL] 29,898 pass(es).
[ View ]

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

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?

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!

> 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.

Status:Needs work» Needs review
StatusFileSize
new1.06 KB
PASSED: [[SimpleTest]]: [MySQL] 31,429 pass(es).
[ View ]

maybe this?

Assigned:barbi» oriol_e9g

Status:Needs review» Reviewed & tested by the community

Yup, that's spot on :)

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

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.

> hook_form_FORM_ID_alter

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

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

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

Status:Patch (to be ported)» Needs review
StatusFileSize
new1.06 KB
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]

patch for 6.x

Status:Needs review» Needs work

Thanks! Small typo: should be MODULE_DELTA not MODULE_DETA.

Assigned:oriol_e9g» Unassigned

Status:Needs work» Needs review
StatusFileSize
new1.06 KB
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]

fixed typo

Status:Needs review» Reviewed & tested by the community

Looks good now, thanks!

Status:Reviewed & tested by the community» Fixed

Thanks, committed, pushed.

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