diff --git a/core/includes/menu.inc b/core/includes/menu.inc
index d1509e0..6e3e5ce 100644
--- a/core/includes/menu.inc
+++ b/core/includes/menu.inc
@@ -861,20 +861,16 @@ function menu_tail_load($arg, &$map, $index) {
  * This function is similar to _menu_translate(), but it also does
  * link-specific preparation (such as always calling to_arg() functions).
  *
- * @param $item
- *   A menu link.
- *
- * @return
- *   Returns the map of path arguments with objects loaded as defined in the
- *   $item['load_functions'].
- *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
- *   $item['href'] is generated from link_path
- *   $item['access'] becomes TRUE if the item is accessible, FALSE otherwise.
- *   $item['title'] is generated from link_title.
- *   $item['route_parameters'] is unserialized if needed.
- *   $item['options'] is unserialized and copied to $item['localized_options'].
- */
-function _menu_link_translate(&$item) {
+ * @param array $item
+ *   The passed in and changed menu item with the following elements:
+ *   - href: The actual path to the link, is generated from link_path
+ *   - access: Becomes TRUE if the item is accessible, FALSE otherwise.
+ *   - title: The title of the link, is generated from link_title.
+ *   - route_name: The route name of the menu link.
+ *   - route_parameters: The unserialized route parameters.
+ *   - options: Is unserialized and copied to $item['localized_options'].
+ */
+function _menu_link_translate(array &$item) {
   if (!is_array($item['options'])) {
     $item['options'] = (array) unserialize($item['options']);
   }
diff --git a/core/modules/menu_link/lib/Drupal/menu_link/MenuLinkStorageController.php b/core/modules/menu_link/lib/Drupal/menu_link/MenuLinkStorageController.php
index ea41970..f59b6e7 100644
--- a/core/modules/menu_link/lib/Drupal/menu_link/MenuLinkStorageController.php
+++ b/core/modules/menu_link/lib/Drupal/menu_link/MenuLinkStorageController.php
@@ -26,6 +26,7 @@ class MenuLinkStorageController extends DatabaseStorageController implements Men
 
   /**
    * Contains all {menu_router} fields without weight.
+   *
    * @var array
    */
   protected static $routerItemFields;
diff --git a/core/modules/system/lib/Drupal/system/Tests/Menu/LinksTest.php b/core/modules/system/lib/Drupal/system/Tests/Menu/LinksTest.php
index c3da82b..bb3b310 100644
--- a/core/modules/system/lib/Drupal/system/Tests/Menu/LinksTest.php
+++ b/core/modules/system/lib/Drupal/system/Tests/Menu/LinksTest.php
@@ -183,7 +183,7 @@ function testMenuLinkReparenting($module = 'menu_test') {
   }
 
   /**
-   * Test automatic reparenting of menu links derived from hook_default_men_links.
+   * Tests automatic reparenting of menu links derived from hook_default_menu_links.
    */
   function testMenuLinkRouterReparenting() {
     // Run all the standard parenting tests on menu links derived from
diff --git a/core/modules/system/system.api.php b/core/modules/system/system.api.php
index 2b6715c..3e69fe2 100644
--- a/core/modules/system/system.api.php
+++ b/core/modules/system/system.api.php
@@ -491,45 +491,66 @@ function hook_menu_get_item_alter(&$router_item, $path, $original_map) {
 /**
  * Define links for menus.
  *
- * @return
- *   An array of default menu links. Each link has a key corresponding to a
- *   unique machine name. The corresponding array value is an
+ * @return array
+ *   An array of default menu links. Each link has a key that is the machine
+ *   name, which must be unique. The corresponding array value is an
  *   associative array that may contain the following key-value pairs:
- *   - "link_title": Required. The untranslated title of the menu item.
+ *   - link_title: (required) The untranslated title of the menu item.
  *     with path component substitution as described above.
- *   - "description": The untranslated description of the link.
- *   - "route_name": Required. The untranslated title of the menu item.
- *   - "route_parameters": Required. The untranslated title of the menu item.
- *   - "link_path": Optional. Generally used for external links.
- *   - "parent": Optional. The machine name of a link to define hierarchy.
- *   - "weight": An integer that determines the relative position of items in
+ *   - description: The untranslated description of the link.
+ *   - route_name: (required) The route name to be used to build the path.
+ *   - route_parameters: (required) The route parameters to build the path.
+ *   - link_path: (optional) If you have an external link use link_path instead
+ *     of providing a route_name.
+ *   - parent": (optional) The machine name of a link to define hierarchy.
+ *   - weight: An integer that determines the relative position of items in
  *     the menu; higher-weighted items sink. Defaults to 0. Menu items with the
  *     same weight are ordered alphabetically.
- *   - "menu_name": Optional. Set this to a custom menu if you don't want your
+ *   - menu_name: (optional) Set this to a custom menu if you don't want your
  *     item to be placed in the default Tools menu.
- *   - "expanded": Optional. If set to TRUE, and if a menu link is provided for
+ *   - expanded: (optional) If set to TRUE, and if a menu link is provided for
  *     this menu item (as a result of other properties), then the menu link is
  *     always expanded, equivalent to its 'always expanded' checkbox being set
  *     in the UI.
- *   - "type": A bitmask of flags describing properties of the menu item.
+ *   - type: (optional) A bitmask of flags describing properties of the menu item.
  *     Many shortcut bitmasks are provided as constants in menu.inc:
  *     - MENU_NORMAL_ITEM: Normal menu items show up in the menu tree and can be
  *       moved/hidden by the administrator.
  *     - MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the
  *       administrator may enable.
  *     If the "type" element is omitted, MENU_NORMAL_ITEM is assumed.
- *   - "options": An array of options to be passed to l() when generating a link
+ *   - options: An array of options to be passed to l() when generating a link
  *     from this menu item.
+ *
+ * @see hook_default_menu_links_alter
  */
 function hook_default_menu_links() {
+  $links['user'] = array(
+    'link_title' => 'My account',
+    'weight' => -10,
+    'route_name' => 'user.page',
+    'menu_name' => 'account',
+  );
 
+  $links['user.logout'] = array(
+    'link_title' => 'Log out',
+    'route_name' => 'user.logout',
+    'weight' => 10,
+    'menu_name' => 'account',
+  );
+
+  return $links;
 }
 
 /**
  * Alter links for menus.
+ *
+ * @see hook_default_menu_links
  */
 function hook_default_menu_links_alter(&$links) {
-
+  // Change the weight and title of the user.logout link.
+  $links['user.logout']['weight'] = -10;
+  $links['user.logout']['link_title'] = ;
 }
 
 /**