Wrong documentation of t()

It actually returns a TranslatableMarkup object.

+++ b/core/includes/bootstrap.inc
@@ -305,7 +305,7 @@ function drupal_get_path($type, $name) {
  * @return

Add @return type \Drupal\Core\StringTranslation\TranslatableMarkup.

Also replace 'The translated string.' in @return comment from translate method in \Drupal\Core\StringTranslation\TranslationInterface.

Good job @all

Good idea to fix up these docs! But:

+++ b/core/includes/bootstrap.inc
@@ -304,8 +304,8 @@ function drupal_get_path($type, $name) {
+ * @return \Drupal\Core\StringTranslation\TranslatableMarkup
+ *   A translated TranslatableMarkup object.

This is not accurate. The returned object is not yet translated when it is returned. The point of that return value (one of them anyway) is that translation is done later.

Same in the other hunk.

i think

A TranslatableMarkup object

will work or

The TranslatableMarkup object

A is better than The here, I think.

35 occurrences for "A something object" in comments based on regex @return [a-zA-Z/\\]*\n \* A [a-zA-Z]+ object

122 occurrences for "The something object" in comments based on regex @return [a-zA-Z/\\]*\n \* The [a-zA-Z]+ object

I prefer The because we ask for the translation of the string passed as param (and not a random translation from many possible translations). So we return the translatableMarkup.

"The" requires an antecedent, and "A" is for introducing a new thing, grammatically. There are plenty of cases where "the" is appropriate to start a @return, like "The input $foo, transformed by bar baz.".

But in this case, the object doesn't exist before this function call. So the return docs should be something like:

A new foobar object that, when cast to a string, will result in the translated string.

Done as suggested by @jhodgdon

Not really what I suggested?

Hi Jhodgdon,
Made the changes.

Done as suggested by @Chi

Hi Chi,
Made the changes

Hi Chi,
Made the changes

It's technically meaningful to say "new" actually... not a bad idea... I think this is fine. Thanks!

cool. it is great to find this being fixed.

+++ b/core/lib/Drupal/Core/StringTranslation/TranslationInterface.php
@@ -34,7 +34,8 @@
+   *   A new TranslatableMarkup object that, when cast to a string, will result
+   *   in the translated string.

I had a similar change in #2578377: Make translatable docs consolidated and better for developers
but used slightly different words "An object that, when cast to a string, will yield the translated string."

I like @YesCT's version - fixed on commit. Committed fd6f9cb and pushed to 8.0.x. Thanks!