Issue #2585781 by anil280988, Davinder.Snehi, sdstyles, lucian.gutoiu, Chi, jhodgdon, GoZ, YesCT: Wrong documentation of t()

core/includes/bootstrap.inc

@@ -304,8 +304,8 @@ function drupal_get_path($type, $name) {
  *   - 'context' (defaults to the empty context): The context the source string
  *     belongs to.
  *
- * @return
- *   The translated string.
+ * @return \Drupal\Core\StringTranslation\TranslatableMarkup
+ *   An object that, when cast to a string, will yield the translated string.
  *
  * @see \Drupal\Component\Utility\SafeMarkup::format()
  * @ingroup sanitization

core/lib/Drupal/Core/StringTranslation/TranslationInterface.php

@@ -34,7 +34,7 @@ interface TranslationInterface {
    *   - 'context': The context the source string belongs to.
    *
    * @return \Drupal\Core\StringTranslation\TranslatableMarkup
-   *   The translated string.
+   *   An object that, when cast to a string, will yield the translated string.
    *
    * @see \Drupal\Component\Utility\SafeMarkup::format()
    */