diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 9dc75de61782dc2a5ae733bfa61c74265b74b043..1f6dd9e8e30a274c70f84b50a1d6b11cc144749a 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -519,7 +519,7 @@
  * @{
  * API for user accounts, access checking, roles, and permissions.
  *
- * @sec sec_overview Overview and terminology
+ * @section sec_overview Overview and terminology
  * Drupal's permission system is based on the concepts of accounts, roles,
  * and permissions.
  *
@@ -550,8 +550,8 @@
  * appropriately for their particular sites.
  *
  * @section sec_define Defining permissions
- * Modules define permissions via a $module.permissions.yml file. The return
- * value defines machine names, human-readable names, and optionally
+ * Modules define permissions via a $module.permissions.yml file. This file
+ * defines machine names, human-readable names, and optionally
  * descriptions for each permission type. The machine names are the canonical
  * way to refer to permissions for access checking.
  *