Minor improvement of the documentation page for t()

Hmm...

Parameters

$string A string containing the English string to translate.

The @param is normally the correct place to mention specifics of a parameter...

That said, if you can fit this into the one-line description, something like
Translates a string from English to ...
in less than 80 characters, I'd say go for it.

Otherwise, if it doesn't fit in 80 characters, I'm afraid it's a "won't fix". Thoughts?

I think a good way to do this would be in the opening paragraph. Something like (added sentence in bold):

The t() function serves two purposes. First, at run-time it translates user-visible text into the appropriate language. Second, various mechanisms that figure out what text needs to be translated work off t() -- the text inside t() calls is added to the database of strings to be translated. These texts are expected to be in English, so the first argument should always be a string in English. To enable a fully-translatable site, it is important that all human-readable text that will be displayed on the site or sent to a user is passed through the t() function, or a related function. See the Localization API pages for more information, including recommendations on how to break up or not break up strings for translation.

Putting this in the initial one-line description makes it easy to overlook it, and does not give a rationale. Having it in the first paragraph means we can be more explicit, it would still be visible without scrolling, and people would see it when they try to figure out what t() does.

I have no objection to this idea. But it should say "This text" instead of "These texts". Text (I think) is not a countable noun in English.

@jhodgdon: I think you are right about "text". Anyhow, I went with "these strings", because it really refers back to the strings stored in the database for translation.

Patch attached. Also applies cleanly to 7.x.

Looks fine, thanks!

Committed to 8.x. Thanks.

Did this patch not apply to D7? I'll retest...

#7: 1265294-doc-t.patch queued for re-testing.

Committed and pushed to 7.x. Thanks!