Incomplete return values documented for system_retrieve_file

Thanks for filing this issue! I agree completely with your analysis.

We need to fix this in drupal 8.x first, and then backport to 7. In 8, the return value for a managed file is a \Drupal\file\FileInterface file entity (see file_save_data() function).

Thanks! This issue can stay about just the documentation then.

I can work on this.

I think this return value documentation would be clearer if it was formatted as a list? Something like:

One of these possibilities:
- If it succeeds and $managed is FALSE, ...
- If it succeeds and $managed is TRUE, ...
- If it fails, FALSE.

I also changed the variable comments for this function from "@param $name type" to "@param type $name". I hope there is no problem with this.

Thanks! Definitely those changes are welcome, and it is common in documentation patches to fix other errors in the same function documentation that is being fixed up.

However, you should use "bool" and not "boolean" for param/return types. There's documentation on this at:
https://drupal.org/coding-standards/docs#types

For extra credit, you could also remove the blank lines between the @param documentation (there should be a blank line between the end of the @param section and @return however).

Do you think it would also make sense on this line:

+ *   - If it succeeds and $managed is TRUE, \Drupal\file\FileInterface.

to have some description of what this means, like "a \Drupal\file\FileInterface object with information about the saved file"? or something like that?

Added new patch because previous one failed.

15: Incomplete-return-values-documented-for-system_retrieve_file-2174353-15.patch queued for re-testing.

Great, thanks!

There is an "avoid commit conflicts" issue that also touches the system.module file: #1996238: Replace hook_library_info() by *.libraries.yml file

I'm being extra careful about these "avoid commit conflicts" issues, so I'm going to postpone committing this until that one is taken care of.

Thanks all! I was able to commit this to both 8.x and 7.x, since I got leave from the authors of that other issue to commit it.