diff --git a/core/modules/block/lib/Drupal/block/Annotation/Block.php b/core/modules/block/lib/Drupal/block/Annotation/Block.php
index 64987e6..87331b8 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 85f615c..3b32fcd 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 4f6bdc2..92cabcc 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 c8a5ede..889b29a 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -68,13 +68,28 @@
  * @{
  * 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:
+ * - Create a Block plugin. See the @link plugin_api Plugin API topic @endlink
+ *   for more information about plugins.
+ * - Block plugins must implement the \Drupal\block\BlockPluginInterface.
+ * - 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.
+ *
+ * \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 more information, see https://drupal.org/developing/api/8/block_api or
+ * the Block example in https://drupal.org/project/examples.
  */
 
 /**