diff -u b/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
--- b/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -353,8 +353,8 @@
  * @param $exception
  *   The exception that is going to be logged.
  * @param $message
- *   (optional) The message to store in the log. If empty, a text that contains
- *   all useful information about the passed-in exception is used.
+ *   (optional) The message to store in the log. If empty, a message is
+ *   generated containing exception information.
  * @param $variables
  *   (optional) An array of variables to replace in the message on display or
  *   NULL if message is already translated or not possible to
@@ -902,7 +902,7 @@
  * Resets one or all centrally stored static variable(s).
  *
  * @param $name
- *   (optional) The Name of the static variable to reset. Omit to reset all
+ *   (optional) The name of the static variable to reset. Omit to reset all
  *   variables. Resetting all variables should only be used, for example,
  *   for running unit tests with a clean environment.
  */
@@ -932,12 +932,12 @@
  * avoid "Exception thrown without a stack frame in Unknown".
  *
  * @param $callback
- *   (optional) The shutdown function to register.
+ *   (optional) An additional shutdown function to register().
  * @param ...
- *   Additional arguments to pass to the shutdown function.
+ *   (optional) Additional arguments to pass to the shutdown function.
  *
- * @return
- *   Array of shutdown functions to be executed.
+ * @return array
+ *   The list of all registered shutdown functions.
  *
  * @see register_shutdown_function()
  * @ingroup php_wrappers
diff -u b/core/includes/common.inc b/core/includes/common.inc
--- b/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -242,8 +242,8 @@
  * @param $size
  *   A size in bytes.
  * @param $langcode
- *   (optional) The Language code to translate to a language other than
- *   what is used to display the page.
+ *   (optional) A language code, to translate to a language other than what is
+ *   used to display the page.
  *
  * @return \Drupal\Core\StringTranslation\TranslatableMarkup
  *   A translated string representation of the size.
diff -u b/core/includes/database.inc b/core/includes/database.inc
--- b/core/includes/database.inc
+++ b/core/includes/database.inc
@@ -322,7 +322,7 @@
  *
  * @param $key
  *   (optional) The key in the $databases array to set as the default database.
- *   By default key is set to 'default'.
+ *   Defaults to 'default'.
  *
  * @return string|null
  *   The key of the formerly active database.
@@ -459,9 +459,9 @@
  * the last ID inserted.
  *
  * @param int $existing_id
- *   (optional) After a database import, it might be that the sequences
- *   table is behind, so by passing in a minimum ID, it can be assured that
- *   we never issue the same ID.
+ *   (optional) After a database import, it could be that the sequences
+ *   table is behind. Passing in a minimum ID ensures that we never issue
+ *   the same ID.
  *
  * @return int
  *   An integer number larger than any number returned before for this sequence.
diff -u b/core/includes/entity.inc b/core/includes/entity.inc
--- b/core/includes/entity.inc
+++ b/core/includes/entity.inc
@@ -55,7 +55,7 @@
  *   The id of the entity to load.
  * @param bool $reset
  *   (optional) Whether to reset the internal cache for the requested
- *   entity type.
+ *   entity type. Defaults to FALSE.
  *
  * @return \Drupal\Core\Entity\EntityInterface|null
  *   The entity object, or NULL if there is no entity with the given ID.
@@ -161,7 +161,7 @@
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
  * @param bool $reset
  *   (optional) Whether to reset the internal cache for the requested
- *   entity type.
+ *   entity type. Defaults to FALSE.
  *
  * @return array
  *   An array of entity objects indexed by their IDs.
diff -u b/core/includes/errors.inc b/core/includes/errors.inc
--- b/core/includes/errors.inc
+++ b/core/includes/errors.inc
@@ -93,9 +93,10 @@
  *
  * @param $error
  *   (optional) An error to examine for ERROR_REPORTING_DISPLAY_SOME.
+ *   Defaults to NULL.
  *
- * @return
- *   TRUE if an error should be displayed.
+ * @return bool
+ *   TRUE if an error should be displayed. FALSE otherwise.
  */
 function error_displayable($error = NULL) {
   if (defined('MAINTENANCE_MODE')) {
@@ -120,7 +121,7 @@
  *   with the exception of @message, which needs to be an HTML string, and
  *   backtrace, which is a standard PHP backtrace.
  * @param $fatal
- *   (optional) TRUE if the error is fatal.
+ *   (optional) TRUE if the error is fatal. Defaults to FALSE.
  */
 function _drupal_log_error($error, $fatal = FALSE) {
   $is_installer = drupal_installation_attempted();
diff -u b/core/includes/file.inc b/core/includes/file.inc
--- b/core/includes/file.inc
+++ b/core/includes/file.inc
@@ -293,9 +293,9 @@
  * @param $options
  *   (optional) A bitmask to indicate if the directory should be created if it
  *   does not exist (FILE_CREATE_DIRECTORY) or made writable if it is read-only
- *   (FILE_MODIFY_PERMISSIONS).
+ *   (FILE_MODIFY_PERMISSIONS). Defaults to FILE_MODIFY_PERMISSIONS.
  *
- * @return
+ * @return bool
  *   TRUE if the directory exists (or was created) and is writable. FALSE
  *   otherwise.
  */
@@ -402,7 +402,7 @@
  * @param $uri
  *   The URI to be tested.
  *
- * @return
+ * @return bool
  *   TRUE if the URI is allowed.
  */
 function file_valid_uri($uri) {
@@ -439,12 +439,12 @@
  *   usually "public://".
  * @param $replace
  *   (optional) Replace behavior when the destination file already exists:
- *   - FILE_EXISTS_REPLACE - Replace the existing file.
- *   - FILE_EXISTS_RENAME (default) - Append _{incrementing number} until
+ *   - FILE_EXISTS_REPLACE: Replace the existing file.
+ *   - FILE_EXISTS_RENAME: (default) Append _{incrementing number} until
  *     the filename is unique.
- *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
+ *   - FILE_EXISTS_ERROR: Do nothing and return FALSE.
  *
- * @return
+ * @return URI|FALSE
  *   The path to the new file, or FALSE in the event of an error.
  *
  * @see file_copy()
@@ -537,12 +537,12 @@
  *   A string specifying the desired final URI or filepath.
  * @param $replace
  *   Replace behavior when the destination file already exists.
- *   - FILE_EXISTS_REPLACE - Replace the existing file.
- *   - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is
- *       unique.
- *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
+ *   - FILE_EXISTS_REPLACE: Replace the existing file.
+ *   - FILE_EXISTS_RENAME: Append _{incrementing number} until the filename is
+ *     unique.
+ *   - FILE_EXISTS_ERROR: Do nothing and return FALSE.
  *
- * @return
+ * @return  URI|FALSE
  *   The destination filepath, or FALSE if the file already exists
  *   and FILE_EXISTS_ERROR is specified.
  */
@@ -578,12 +578,12 @@
  *   Drupal's default files scheme will be used, usually "public://".
  * @param $replace
  *   (optional) Replace behavior when the destination file already exists:
- *   - FILE_EXISTS_REPLACE - Replace the existing file.
- *   - FILE_EXISTS_RENAME (default) - Append _{incrementing number} until the filename is
- *       unique.
- *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
+ *   - FILE_EXISTS_REPLACE: Replace the existing file.
+ *   - FILE_EXISTS_RENAME: (default) Append _{incrementing number} until the
+ *     filename is unique.
+ *   - FILE_EXISTS_ERROR: Do nothing and return FALSE.
  *
- * @return
+ * @return URI|FALSE
  *   The URI of the moved file, or FALSE in the event of an error.
  *
  * @see file_move()
@@ -614,15 +614,17 @@
  * included in $extensions.
  *
  * Function behavior is also controlled by the configuration
- * 'system.file:allow_insecure_uploads'. If it evaluates to TRUE, no alterations
- * will be made, if it evaluates to FALSE, the filename is 'munged'. *
+ * 'system.file:allow_insecure_uploads'. If it evaluates to TRUE, no
+ * alterations will be made, if it evaluates to FALSE, the filename is
+ * 'munged'.
+ *
  * @param $filename
  *   File name to modify.
  * @param $extensions
  *   A space-separated list of extensions that should not be altered.
  * @param $alerts
  *   (optional) If TRUE, drupal_set_message() will be called to display
- *   a message if the file name was changed.
+ *   a message if the file name was changed. Defaults to TRUE.
  *
  * @return string
  *   The potentially modified $filename.
@@ -874,12 +876,12 @@
  *   usually "public://".
  * @param $replace
  *   (optional) Replace behavior when the destination file already exists:
- *   - FILE_EXISTS_REPLACE - Replace the existing file.
- *   - FILE_EXISTS_RENAME (default) - Append _{incrementing number} until the
+ *   - FILE_EXISTS_REPLACE: Replace the existing file.
+ *   - FILE_EXISTS_RENAME: (default) Append _{incrementing number} until the
  *     filename is unique.
- *   - FILE_EXISTS_ERROR - Do nothing and return FALSE.
+ *   - FILE_EXISTS_ERROR: Do nothing and return FALSE.
  *
- * @return
+ * @return URI|FALSE
  *   A string with the path of the resulting file, or FALSE on error.
  *
  * @see file_save_data()
@@ -927,10 +929,10 @@
  *   - 'min_depth': Minimum depth of directories to return files from. Defaults
  *     to 0.
  * @param $depth
- *   (optional) The current depth of recursion. This parameter is only used internally and
- *   should not be passed in.
+ *   (optional) The current depth of recursion. This parameter is only used
+ *   internally and should not be passed in.
  *
- * @return
+ * @return array
  *   An associative array (keyed on the chosen key) of objects with 'uri',
  *   'filename', and 'name' properties corresponding to the matched files.
  */