Resolve PHP code inspection warnings and errors in core /includes directory

[quicksketch]

Similar to #1868, this issue is to resolve PHP inspection warnings and errors in the entire /core/includes directory. This includes fixing things like the following:

• Missing docblocks.
• Inconsistent return values or unspecified return values.
• Removing unused variables.
• Ensuring that @return values are accurate and interpreted correctly from callers.

This sort of checking reduces the errors reported by PHPStorm and other IDEs, allowing their inspection abilities to appropriately flag real problems in our code base. It also helps with autocompletion. And of course it should result in more complete and accurate documentation for real users reading the code or the docs on api.backdropcms.org.

[quicksketch]

PR filed at backdrop/backdrop#1419.

[quicksketch]

While fixing a PHP inspection warning in file.inc, I ran across a bug in creating new file entities. New issue at #1938.

[quicksketch]

Merged in backdrop/backdrop#1419, it's only fixing a small (but critical) part of the documentation in Backdrop core, but it reduces the inspection warnings substantially. This will be in 1.4.3.

[klonos]

👏 for reducing annoyances.

[quicksketch]

I found that PHP 7's error handling doesn't work quite right with one of these changes. We made it so that _backdrop_decode_exception() took a type hint of Exception, but in PHP 7, this may be either an Exception or Error object. PR filed to fix this at backdrop/backdrop#1431.

[quicksketch]

Merged backdrop/backdrop#1431. Again for 1.4.3.