Comments #36-#41 suggest that some clarification is needed in the l() function docs. I've found docs and usage in the mentioned issue somewhat confusing myself. Taking a first stab at it and awaiting for feedback.

Files: 
CommentFileSizeAuthor
#20 drupal--1837840--possible-improvement-l-function-docs-20.patch1.04 KBamontero
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]
#15 drupal--1837840--possible-improvement-l-function-docs-15.patch1.08 KBamontero
PASSED: [[SimpleTest]]: [MySQL] 48,060 pass(es).
[ View ]
#13 drupal--1837840--possible-improvement-l-function-docs-13.patch1.13 KBamontero
PASSED: [[SimpleTest]]: [MySQL] 48,059 pass(es).
[ View ]
#6 drupal--1837840--possible-improvement-l-function-docs-6.patch1.13 KBamontero
PASSED: [[SimpleTest]]: [MySQL] 48,058 pass(es).
[ View ]
#4 drupal--1837840--possible-improvement-l-function-docs-4.patch1.12 KBamontero
PASSED: [[SimpleTest]]: [MySQL] 48,061 pass(es).
[ View ]
#3 drupal--1837840--possible-improvement-l-function-docs-3.patch1.1 KBamontero
PASSED: [[SimpleTest]]: [MySQL] 48,047 pass(es).
[ View ]
drupal--possible-improvement-l-function-docs.patch1.08 KBamontero
PASSED: [[SimpleTest]]: [MySQL] 47,997 pass(es).
[ View ]

Comments

Status:Needs review» Needs work

Looks good already. I have a small suggestion for improvement. Instead of:

However, for links enclosed in translatable texts you should use t('Your admin page', array('@url' => url('admin'))) style to keep strings in context for translation.

I think the following would be clearer:

However, for links enclosed in translatable texts you should use t() and embed the HTML anchor tag directly in the translated string. For example:
@code
t('Your admin page', array('@url' => url('admin')));
@endcode
This keeps the context of the link title ('admin' in the example) translators.

I.e. I think it would be nice to actually say what the best practice in this case is, and then give an example. As a added bonus, api.drupal.org will automatically link "t()" to the respective page.

And I would also note that "texts" should be "text" in "enclosed in translatable text". :)

Status:Needs work» Needs review
StatusFileSize
new1.1 KB
PASSED: [[SimpleTest]]: [MySQL] 48,047 pass(es).
[ View ]

Much clearer that way, for sure. Rock'n'reroll.

StatusFileSize
new1.12 KB
PASSED: [[SimpleTest]]: [MySQL] 48,061 pass(es).
[ View ]

Doh, example link was missing.

Status:Needs review» Needs work

Almost there. Two minor oversights:

+++ b/core/includes/common.inc
@@ -2268,6 +2268,12 @@ function drupal_http_header_attributes(array $attributes = array()) {
+ * t('Your admin page', array('@url' => url('admin')));

This is missing the <a href="@url"> part in the example code.

+++ b/core/includes/common.inc
@@ -2268,6 +2268,12 @@ function drupal_http_header_attributes(array $attributes = array()) {
+ * This keeps the context of the link title ('admin' in the example) translators.

... FOR translators. (missing "for"; this might mean you'll have to wrap the line, don't know)

Status:Needs work» Needs review
StatusFileSize
new1.13 KB
PASSED: [[SimpleTest]]: [MySQL] 48,058 pass(es).
[ View ]

If we want to be really nice, we would also say "administrative" and not "admin" in the text of the example. :)

Status:Needs review» Needs work

Actually, can we make a more realistic example from core?

IMO, the example should be left as is, because the simpler the example, the better. I doubt that a core example can be more understandable at all and that's precisely the point of the example. So keeping it as short/simple as possible is a plus for me.

Well, can it at least be a bit more realistic? I can't imagine anyone actually writing "Your admin page" in text. Maybe something like "Visit the [link]Mymodule settings page[endlink]" instead?

How about "Visit the settings page" ?
It keeps it short and without wrapping and it's a more realistic example, as you suggested.

Sure!

Title:Possible improvement to l() function docsImprovement to l() function docs
Status:Needs work» Needs review
StatusFileSize
new1.13 KB
PASSED: [[SimpleTest]]: [MySQL] 48,059 pass(es).
[ View ]

Status:Needs review» Needs work

That looks good, thanks! The only thing (sorry for not noticing it earlier) is that the new text should start on the previous line (all docs comments should wrap as close to 80 characters per line as possible without going over). Or if you think it should be a new paragraph, leave a blank (*) line.

StatusFileSize
new1.08 KB
PASSED: [[SimpleTest]]: [MySQL] 48,060 pass(es).
[ View ]

Status:Needs work» Needs review

Status:Needs review» Reviewed & tested by the community

That looks great. Thanks for sticking with this!

Status:Reviewed & tested by the community» Fixed
Issue tags:-documentation, -documentation bug

Thanks! Committed to 8.x and 7.x. I also removed some extraneous tags from this issue (please read the issue tag guidelines! the link is under the Tags field in the help/description text).

Version:8.x-dev» 6.x-dev
Status:Fixed» Needs review
Issue tags:+needs backport to D6
StatusFileSize
new1.04 KB
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]

As a comment-only modification, looks both safe and worthwile improving also 6.x docs.

Status:Needs review» Reviewed & tested by the community

Straight backport. Looks good. :-)

Status:Reviewed & tested by the community» Fixed

Good idea -- committed this to 6.x.

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