docs for t() and related functions don't explain how context works

It's an arbitrary string, which is why it isn't really explained...

There is some explanation here for 8:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Language!language...
and there are a bunch of 8.x functions with the same args, like TranslationInterface::translate() and for that matter t() and StringTranslationTrait::t(), that would need this documentation updated if we're going to update it for the D7 t() function.

So for D8 functions, we should do something like:

See the @link i18n Internationalization topic @endlink for more information about string contexts.

In D7, we don't have this topic, so we'd need to write something (preferably short) and then maybe link to that localize.drupal.org page.

Here Its the Patch!

Thanks for trying! The patch needs some work though:

+++ b/core/includes/bootstrap.inc
@@ -284,6 +284,9 @@ function drupal_get_path($type, $name) {
+ *See the @link i18n Internationalization topic @endlink for more information ¶

This line has an extra space at the end. And it needs a space at the beginning between the * and the text.

Also rather than being its own paragraph, it should be added above at the end of the text that mentions 'context'.

This comment applies to the other two places this was put into the patch as well.

This is how I understood what you wrote. Please let me know if there is anything to be changed.
Regards.

Closer!

1. +++ b/core/includes/bootstrap.inc
   @@ -281,8 +281,9 @@ function drupal_get_path($type, $name) {
   - *   - 'context' (defaults to the empty context): The context the source string
   - *     belongs to.
   + *   - 'context' (defaults to the empty context): The context the source
   + *     string belongs to. See the @link i18n Internationalization topic
   + *     @endlink for more information about string contexts.
   

   Yes, that is what I meant.

   However:

   - Why did you move the word "string" down to the next line? It was better up where it was. We want documentation lines to wrap as close to 80 characters as possible, without going over.

   - @link ... @endlink has to stay on the same line. I think if you move "string" back up a line, you'll be able to fit the @endlink there... if not, then you would need to move the whole @link ... @endlink down to the next line.

2. +++ b/core/lib/Drupal/Core/StringTranslation/StringTranslationTrait.php
   @@ -60,7 +60,8 @@
   +   *     string belongs to. See the @link i18n Internationalization topic
   +   *     @endlink for more information about string contexts.
   

   Here, move @link ... @endlink down to the next line.

3. +++ b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
   @@ -38,7 +38,8 @@
   +   *     string belongs to. See the @link i18n Internationalization topic
   +   *     @endlink for more information about string contexts.
   

   Here too.

.

Unrelated test failure.

Thanks! patch looks good now.

Unrelated test failure.

Committed/pushed to all three 8.x branches. Moving to 7.x for backport.

This is the patch for Drupal 7.

Thanks! It's pretty good... a few small suggestions:

1. +++ b/includes/bootstrap.inc
   @@ -1450,7 +1450,11 @@ function drupal_unpack($obj, $field = 'data') {
   + *     @link https://localize.drupal.org/node/2109 localize.drupal.org @endlink
   

   It would be better, in this line, to just put in the URL directly rather than making an @link ... @endlink.

2. +++ b/includes/bootstrap.inc
   @@ -1450,7 +1450,11 @@ function drupal_unpack($obj, $field = 'data') {
   + *     to know more about contexts.
   

   know -> learn

Sure, thanks!

Better!

So ... sorry I didn't look at this before... but let's compare this patch to the 8.x patch.

8.x, after patching:

 *   - 'context' (defaults to the empty context): The context the source string
 *     belongs to. See the @link i18n Internationalization topic @endlink for
 *     more information about string contexts.
 *     belongs to. See the @link i18n Internationalization topic @endlink for
 *     more information about string contexts.

And the internationalization topic says (in part):

By default, translated strings are only translated once, no matter where they are being used. ...

Because the source of translation strings is English, and some words in English have multiple meanings or uses, this centralized, shared translation string storage can sometimes lead to ambiguous translations that are not correct for every place the string is used. .....

And here is what is in the current patch for 7.x:

 *   - 'context' (defaults to the empty context): The context the source string
 *     belongs to. Contexts are a good way to solve translation conflicts,
 *     when short strings are impossible to translate in different ways
 *     otherwise. Visit https://localize.drupal.org/node/2109 to learn more
 *     about contexts.

So... Since we don't have a topic that explains context in more detail in 7.x, I like that you put in more information in the 7.x doc block for t() than we had in the 8.x block. But I'm not sure that this text really explains the problem very well...

What about something like this?

Note: I didn't bother with an interdiff file since it's the same exact lines as the patch itself (all patched lines changed).

Looks great. Thanks!

Marked for commit, thanks!

This looks great, thanks!

Committed to 7.x - thanks!

- *   - 'context' (defaults to the empty context): The context the source string
- *     belongs to.
+ *   - 'context' (defaults to the empty context): A string giving the context
+ *     that the source string belongs to. See @ref sec_context above for more
+ *     information.

Just a note that the "@ref sec_context" doesn't seem to be working (it's just displayed as is at https://api.drupal.org/api/drupal/includes%21bootstrap.inc/function/t/7.x - no automatic link to the section). Not sure if that's something that should be fixed on api.drupal.org or if we should just remove it from the code here instead.

How about See the "String context" section above for more information (no link) for now?

Interestingly the @ref tag does seem to work on in D8 core documentation

That sounds good to me.