diff --git a/core/modules/block/lib/Drupal/block/Annotation/Block.php b/core/modules/block/lib/Drupal/block/Annotation/Block.php
index ec093be5cb0ebd8c658cec9f3613ee3777a96406..1f043c4f21492273fe7bd67903dde94f3986b303 100644
--- a/core/modules/block/lib/Drupal/block/Annotation/Block.php
+++ b/core/modules/block/lib/Drupal/block/Annotation/Block.php
@@ -12,6 +12,8 @@
 /**
  * Defines a Block annotation object.
  *
+ * @ingroup block_api
+ *
  * @Annotation
  */
 class Block extends Plugin {
diff --git a/core/modules/block/lib/Drupal/block/BlockBase.php b/core/modules/block/lib/Drupal/block/BlockBase.php
index 649bafc6427f2536a283e2192013119f36e0f148..e50a18cec2446c2db099afb0c4e1a536129e9db3 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -22,6 +22,8 @@
  * This abstract class provides the generic block configuration form, default
  * block settings, and handling for general user-defined block visibility
  * settings.
+ *
+ * @ingroup block_api
  */
 abstract class BlockBase extends PluginBase implements BlockPluginInterface {
 
diff --git a/core/modules/block/lib/Drupal/block/BlockPluginInterface.php b/core/modules/block/lib/Drupal/block/BlockPluginInterface.php
index 4a25093c07e02b035aef78803f84abfccd8d6824..f45ecc5a2a9887adf842bb6570f6093e406c8592 100644
--- a/core/modules/block/lib/Drupal/block/BlockPluginInterface.php
+++ b/core/modules/block/lib/Drupal/block/BlockPluginInterface.php
@@ -20,6 +20,8 @@
  *   architecture and the relationships between the various objects, including
  *   brif references to the important components that are not coupled to the
  *   interface.
+ *
+ * @ingroup block_api
  */
 interface BlockPluginInterface extends ConfigurablePluginInterface, PluginFormInterface, PluginInspectionInterface, CacheableInterface {
 
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index c8a5edec012807b32ee11cdae599e10ebbc30d90..f2cc90e83ea8171c72e09dc0227fc6a24300fb1c 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -68,13 +68,32 @@
  * @{
  * Information about the classes and interfaces that make up the Block API.
  *
- * @todo write this
- *
- * Additional documentation paragraphs need to be written, and classes and
- * interfaces need to be added to this topic.
- *
- * See https://drupal.org/node/2168137
- * @}
+ * Blocks are a combination of a configuration entity and a plugin. The
+ * configuration entity stores placement information (theme, region, weight) and
+ * any other configuration that is specific to the block. The block plugin does
+ * the work of rendering the block's content for display.
+ *
+ * To define a block in a module you need to:
+ * - Define a Block plugin by creating a new class that implements the
+ *   \Drupal\block\BlockPluginInterface. For more information about how block
+ *   plugins are discovered see the @link plugin_api Plugin API topic @endlink.
+ * - Usually you will want to extend the \Drupal\block\BlockBase class, which
+ *   provides a common configuration form and utility methods for getting and
+ *   setting configuration in the block configuration entity.
+ * - Block plugins use the annotations defined by
+ *   \Drupal\block\Annotation\Block. See the
+ *   @link annotation Annotations topic @endlink for more information about
+ *   annotations.
+ *
+ * Further information and examples:
+ * - \Drupal\system\Plugin\Block\SystemPoweredByBlock provides a simple example
+ *   of defining a block.
+ * - \Drupal\book\Plugin\Block\BookNavigationBlock is an example of a block with
+ *   a custom configuration form.
+ * - For a more in-depth discussion of the Block API see
+ *   https://drupal.org/developing/api/8/block_api
+ * - The examples project also provides a Block example in
+ *   https://drupal.org/project/examples.
  */
 
 /**