diff --git a/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
index ce872d4..21ea6b2 100644
--- a/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -179,7 +179,7 @@ function config_get_config_directory($type) {
  *   The name of the item for which the filename is requested. Ignored for
  *   $type 'core'.
  * @param $filename
- *   The filename of the item if it is to be set explicitly rather
+ *   (optional) The filename of the item if it is to be set explicitly rather
  *   than by consulting the database.
  *
  * @return
@@ -353,16 +353,16 @@ function drupal_validate_utf8($text) {
  * @param $exception
  *   The exception that is going to be logged.
  * @param $message
- *   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
- *   Array of variables to replace in the message on display or
+ *   (optional) An array of variables to replace in the message on display or
  *   NULL if message is already translated or not possible to
  *   translate.
  * @param $severity
  *   The severity of the message, as per RFC 3164.
  * @param $link
- *   A link to associate with the message.
+ *   (optional) A link to associate with the message.
  *
  * @see \Drupal\Core\Utility\Error::decodeException()
  */
@@ -593,7 +593,7 @@ function _drupal_exception_handler_additional($exception, $exception2) {
  * Returns the test prefix if this is an internal request from SimpleTest.
  *
  * @param string $new_prefix
- *   Internal use only. A new prefix to be stored.
+ *   (optional) Internal use only. A new prefix to be stored.
  *
  * @return string|FALSE
  *   Either the simpletest prefix (the string "simpletest" followed by any
@@ -853,11 +853,12 @@ function drupal_classloader_register($name, $path) {
  *   is recommended. For a function with multiple static variables add a
  *   distinguishing suffix to the function name for each one.
  * @param $default_value
- *   Optional default value.
+ *   (optional) The default value.
  * @param $reset
- *   TRUE to reset one or all variables(s). This parameter is only used
- *   internally and should not be passed in; use drupal_static_reset() instead.
- *   (This function's return value should not be used when TRUE is passed in.)
+ *   (optional) TRUE to reset one or all variables(s). This parameter is only
+ *   used internally and should not be passed in; use drupal_static_reset()
+ *   instead. (This function's return value should not be used when TRUE is
+ *   passed in.)
  *
  * @return
  *   Returns a variable by reference.
@@ -901,9 +902,9 @@ function &drupal_static($name, $default_value = NULL, $reset = FALSE) {
  * Resets one or all centrally stored static variable(s).
  *
  * @param $name
- *   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.
+ *   (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.
  */
 function drupal_static_reset($name = NULL) {
   drupal_static($name, NULL, TRUE);
@@ -931,12 +932,12 @@ function drupal_placeholder($text) {
  * avoid "Exception thrown without a stack frame in Unknown".
  *
  * @param $callback
- *   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 --git a/core/includes/common.inc b/core/includes/common.inc
index 5d62aad..97673a7 100644
--- a/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -242,8 +242,8 @@ function check_url($uri) {
  * @param $size
  *   A size in bytes.
  * @param $langcode
- *   Optional 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 --git a/core/includes/database.inc b/core/includes/database.inc
index 477e843..5dec780 100644
--- a/core/includes/database.inc
+++ b/core/includes/database.inc
@@ -35,12 +35,12 @@
  *   an array of values to be expanded, e.g. for an IN query, the placeholder
  *   should be named with a trailing bracket like :example[]
  * @param array $args
- *   An array of values to substitute into the query. If the query uses named
- *   placeholders, this is an associative array in any order. If the query uses
- *   unnamed placeholders (?), this is an indexed array and the order must match
- *   the order of placeholders in the query string.
+ *   (optional) An array of values to substitute into the query. If the query
+ *   uses named placeholders, this is an associative array in any order.
+ *   If the query uses unnamed placeholders (?), this is an indexed array and
+ *   the order must match the order of placeholders in the query string.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\StatementInterface
  *   A prepared statement object, already executed.
@@ -73,12 +73,12 @@ function db_query($query, array $args = array(), array $options = array()) {
  * @param $count
  *   The number of records to return from the result set.
  * @param array $args
- *   An array of values to substitute into the query. If the query uses named
- *   placeholders, this is an associative array in any order. If the query uses
- *   unnamed placeholders (?), this is an indexed array and the order must match
- *   the order of placeholders in the query string.
+ *   (optional) An array of values to substitute into the query. If the query
+ *   uses named placeholders, this is an associative array in any order. If the
+ *   query uses unnamed placeholders (?), this is an indexed array and the
+ *   order must match the order of placeholders in the query string.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\StatementInterface
  *   A prepared statement object, already executed.
@@ -109,12 +109,12 @@ function db_query_range($query, $from, $count, array $args = array(), array $opt
  *   named and unnamed placeholders, named placeholders are strongly preferred
  *   as they are more self-documenting.
  * @param array $args
- *   An array of values to substitute into the query. If the query uses named
- *   placeholders, this is an associative array in any order. If the query uses
- *   unnamed placeholders (?), this is an indexed array and the order must match
- *   the order of placeholders in the query string.
+ *   (optional) An array of values to substitute into the query. If the query
+ *   uses named placeholders, this is an associative array in any order. If the
+ *   query uses unnamed placeholders (?), this is an indexed array and the
+ *   order must match the order of placeholders in the query string.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return
  *   The name of the temporary table.
@@ -141,7 +141,7 @@ function db_query_temporary($query, array $args = array(), array $options = arra
  * @param string $table
  *   The table into which to insert.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Insert
  *   A new Insert object for this connection.
@@ -166,7 +166,7 @@ function db_insert($table, array $options = array()) {
  * @param string $table
  *   Name of the table to associate with this query.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Merge
  *   A new Merge object for this connection.
@@ -191,7 +191,7 @@ function db_merge($table, array $options = array()) {
  * @param string $table
  *   The table to update.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Update
  *   A new Update object for this connection.
@@ -216,7 +216,7 @@ function db_update($table, array $options = array()) {
  * @param string $table
  *   The table from which to delete.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Delete
  *   A new Delete object for this connection.
@@ -241,7 +241,7 @@ function db_delete($table, array $options = array()) {
  * @param string $table
  *   The table from which to truncate.
  * @param array $options
- *   An array of options to control how the query operates.
+ *   (optional) An array of options to control how the query operates.
  *
  * @return \Drupal\Core\Database\Query\Truncate
  *   A new Truncate object for this connection.
@@ -294,9 +294,9 @@ function db_select($table, $alias = NULL, array $options = array()) {
  * Returns a new transaction object for the active database.
  *
  * @param string $name
- *   Optional name of the transaction.
+ *   (optional) The name of the transaction.
  * @param array $options
- *   An array of options to control how the transaction operates:
+ *   (optional) An array of options to control how the transaction operates:
  *   - target: The database target name.
  *
  * @return \Drupal\Core\Database\Transaction
@@ -321,7 +321,8 @@ function db_transaction($name = NULL, array $options = array()) {
  * Sets a new active database.
  *
  * @param $key
- *   The key in the $databases array to set as the default database.
+ *   (optional) The key in the $databases array to set as the default database.
+ *   Defaults to 'default'.
  *
  * @return string|null
  *   The key of the formerly active database.
@@ -435,8 +436,8 @@ function db_driver() {
  * Closes the active database connection.
  *
  * @param array $options
- *   An array of options to control which connection is closed. Only the target
- *   key has any meaning in this case.
+ *   (optional) An array of options to control which connection is closed.
+ *   Only the target key has any meaning in this case.
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Use
  *   \Drupal\Core\Database\Database::closeConnection($target).
@@ -458,9 +459,9 @@ function db_close(array $options = array()) {
  * the last ID inserted.
  *
  * @param int $existing_id
- *   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 --git a/core/includes/entity.inc b/core/includes/entity.inc
index 70e8019..692d19a 100644
--- a/core/includes/entity.inc
+++ b/core/includes/entity.inc
@@ -23,8 +23,8 @@ function entity_render_cache_clear() {
  * Returns the entity bundle info.
  *
  * @param string|null $entity_type
- *   The entity type whose bundle info should be returned, or NULL for all
- *   bundles info. Defaults to NULL.
+ *   (optional) The entity type whose bundle info should be returned, or NULL
+ *   for all bundles info. Defaults to NULL.
  *
  * @return array
  *   The bundle info for a specific entity type, or all entity types.
@@ -54,7 +54,8 @@ function entity_get_bundles($entity_type = NULL) {
  * @param mixed $id
  *   The id of the entity to load.
  * @param bool $reset
- *   Whether to reset the internal cache for the requested entity type.
+ *   (optional) Whether to reset the internal cache for the requested
+ *   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.
@@ -159,7 +160,8 @@ function entity_revision_delete($entity_type, $revision_id) {
  * @param array $ids
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
  * @param bool $reset
- *   Whether to reset the internal cache for the requested entity type.
+ *   (optional) Whether to reset the internal cache for the requested
+ *   entity type. Defaults to FALSE.
  *
  * @return array
  *   An array of entity objects indexed by their IDs.
diff --git a/core/includes/errors.inc b/core/includes/errors.inc
index 4795480..a9f5950 100644
--- a/core/includes/errors.inc
+++ b/core/includes/errors.inc
@@ -92,10 +92,11 @@ function _drupal_error_handler_real($error_level, $message, $filename, $line, $c
  * will be examined to determine if it should be displayed.
  *
  * @param $error
- *   Optional error to examine for ERROR_REPORTING_DISPLAY_SOME.
+ *   (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 @@ function error_displayable($error = NULL) {
  *   with the exception of @message, which needs to be an HTML string, and
  *   backtrace, which is a standard PHP backtrace.
  * @param $fatal
- *   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 --git a/core/includes/file.inc b/core/includes/file.inc
index b9c217b..9c94f07 100644
--- a/core/includes/file.inc
+++ b/core/includes/file.inc
@@ -290,11 +290,11 @@ function file_url_transform_relative($file_url) {
  *   A string reference containing the name of a directory path or URI. A
  *   trailing slash will be trimmed from a path.
  * @param $options
- *   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).
+ *   (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). Defaults to FILE_MODIFY_PERMISSIONS.
  *
- * @return
+ * @return bool
  *   TRUE if the directory exists (or was created) and is writable. FALSE
  *   otherwise.
  */
@@ -401,7 +401,7 @@ function file_htaccess_lines($private = TRUE) {
  * @param $uri
  *   The URI to be tested.
  *
- * @return
+ * @return bool
  *   TRUE if the URI is allowed.
  */
 function file_valid_uri($uri) {
@@ -432,17 +432,18 @@ function file_valid_uri($uri) {
  * @param $source
  *   A string specifying the filepath or URI of the source file.
  * @param $destination
- *   A URI containing the destination that $source should be copied to. The
- *   URI may be a bare filepath (without a scheme). If this value is omitted,
- *   Drupal's default files scheme will be used, usually "public://".
+ *   (optional) A URI containing the destination that $source should be
+ *   copied to. The URI may be a bare filepath (without a scheme).
+ *   If this value is omitted, Drupal's default files scheme will be used,
+ *   usually "public://".
  * @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.
+ *   (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.
  *
- * @return
+ * @return string|false
  *   The path to the new file, or FALSE in the event of an error.
  *
  * @see file_copy()
@@ -535,12 +536,12 @@ function file_build_uri($path) {
  *   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  string|false
  *   The destination filepath, or FALSE if the file already exists
  *   and FILE_EXISTS_ERROR is specified.
  */
@@ -571,17 +572,17 @@ function file_destination($destination, $replace) {
  * @param $source
  *   A string specifying the filepath or URI of the original file.
  * @param $destination
- *   A string containing the destination that $source should be moved to.
- *   This must be a stream wrapper URI. If this value is omitted, Drupal's
- *   default files scheme will be used, usually "public://".
+ *   (optional) A string containing the destination that $source should be
+ *   moved to. This must be a stream wrapper URI. If this value is omitted,
+ *   Drupal's default files scheme will be used, usually "public://".
  * @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.
+ *   (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.
  *
- * @return
+ * @return string|false
  *   The URI of the moved file, or FALSE in the event of an error.
  *
  * @see file_move()
@@ -612,15 +613,17 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
  * 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
- *   If TRUE, drupal_set_message() will be called to display a message if the
- *   file name was changed.
+ *   (optional) If TRUE, drupal_set_message() will be called to display
+ *   a message if the file name was changed. Defaults to TRUE.
  *
  * @return string
  *   The potentially modified $filename.
@@ -866,18 +869,18 @@ function drupal_move_uploaded_file($filename, $uri) {
  * @param $data
  *   A string containing the contents of the file.
  * @param $destination
- *   A string containing the destination location. This must be a stream wrapper
- *   URI. If no value is provided, a randomized name will be generated and the
- *   file will be saved using Drupal's default files scheme, usually
- *   "public://".
+ *   (optional) A string containing the destination location. This must be
+ *   a stream wrapper URI. If no value is provided, a randomized name will be
+ *   generated and the file will be saved using Drupal's default files scheme,
+ *   usually "public://".
  * @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.
+ *   (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.
  *
- * @return
+ * @return string|false
  *   A string with the path of the resulting file, or FALSE on error.
  *
  * @see file_save_data()
@@ -910,7 +913,8 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX
  * @param $mask
  *   The preg_match() regular expression for files to be included.
  * @param $options
- *   An associative array of additional options, with the following elements:
+ *   (optional) An associative array of additional options, with the
+ *   following elements:
  *   - 'nomask': The preg_match() regular expression for files to be excluded.
  *     There is no default.
  *   - 'callback': The callback function to call for each match. There is no
@@ -924,10 +928,10 @@ function file_unmanaged_save_data($data, $destination = NULL, $replace = FILE_EX
  *   - 'min_depth': Minimum depth of directories to return files from. Defaults
  *     to 0.
  * @param $depth
- *   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.
  */