StaticTranslation::getLanguage, add @return values in the comment docblocks.

+++ b/core/lib/Drupal/Core/StringTranslation/Translator/StaticTranslation.php
@@ -59,6 +59,8 @@ public function reset() {
+   * @return array
    */

Thanks... but it is not OK to add a @return without a documentation line telling what the return value is.

Thanks for the patch... but I don't think this is really correct.

Looking at StaticTranslation::getLanguage:
- The first line of the doc block is not correct. It says "Add translations for new language" but that is not what it does, and besides which first line doc blocks should start with a verb ending in S.
- The return value docs in the patch are also unclear and incorrect. You need to look at what some of the overriding methods do to get an idea. Start from
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!StringTranslation...
and then look at "2 methods override..."
Also you can look at the method getStringTranslation() that calls this method, to get more of an idea of the structure it returns.

So what it's really doing, I think, is returning all of the translations for the given language, in an array. The documentation should document the structure of this array.

Hi!
It should be more accurate now.

Thanks for the patch! It's getting better, but still needs some work.

1. +++ b/core/lib/Drupal/Core/StringTranslation/Translator/StaticTranslation.php
   @@ -55,10 +55,14 @@ public function reset() {
   +   * Retrieve translations by given language.
   

   Retrieve -> Retrieves
   by given -> for a given

2. +++ b/core/lib/Drupal/Core/StringTranslation/Translator/StaticTranslation.php
   @@ -55,10 +55,14 @@ public function reset() {
   +   * @return array
   +   *   Returns array of translations indexed by language and context or an empty
   +   *   array when no translations are available.
   

   We don't normally start @return docs with "Returns", so just leave that word out.

   Also I don't understand what this is saying. Is it it a multi-dimensional array indexed first by language and second by context... what is context if so? This needs more detail still.

Hi! Thanks for the review!
The return docs should be better now.

Thanks!

+++ b/core/lib/Drupal/Core/StringTranslation/Translator/StaticTranslation.php
@@ -55,10 +55,15 @@ public function reset() {
+   *   A multidimensional array of translations indexed by the context the
+   *   source string belongs to and the original string or an empty array when
+   *   no translations are available.

Better, but still not quite clear:
- Which index is first, context or string?
- Needs punctuation. It is all one long string of text without even a comma. I suggest comma after "translations".
- I also think the "or an empty array" should maybe be made into a separate sentence because it is pretty run-on as it is? At a minimum, needs some punctuation to set that part apart.

Hi!
Thanks for the fast response.
Hopefully this is better now.

Thanks! That is clear enough... maybe we could come up with a slightly better wording, but it is readable and correct, so that makes it Good Documentation (TM). Thanks!

bot fail. :(

Bot failed, marking it back RTBC.

Committed/pushed to 8.1.x and cherry-picked to 8.0.x. Thanks!