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..1a8fb8f 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -22,6 +22,10 @@
  * This abstract class provides the generic block configuration form, default
  * block settings, and handling for general user-defined block visibility
  * settings.
+ *
+ * For additional information see the @link block_api Block API topic @endlink.
+ *
+ * @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 1ecc9c1..4c73167 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -61,21 +61,68 @@
  * - @link https://drupal.org/list-changes API change notices @endlink
  * - @link https://drupal.org/developing/api/8 Drupal 8 API longer references @endlink
  */
-
 /**
  * @defgroup block_api Block API
  * @{
  * 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.
+ * Blocks are the boxes of content that together make up the pages output by
+ * Drupal. These include the "User Login", "Who's online", and "Main page
+ * content" blocks. Blocks can be placed into regions provided by any active
+ * theme via the Block layout UI.
+ *
+ * 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 and and builds the plugin-specific
+ * part of the configuration form.
+ *
+ * Blocks are defined by classes that implement the \Drupal\block\BlockPluginInterface
+ * interface and are an extension of the core
+ * @link https://drupal.org/developing/api/8/plugins Plugin API @endlink. Blocks
+ * are registered with Drupal by using
+ * @link https://drupal.org/node/1882526 annotated plugin discovery @endlink.
+ *
+ * Core provides the \Drupal\block\BlockBase class that can be extended to
+ * create custom blocks. BlockBase provides a basic configuration form and
+ * utility methods for interacting with the configuration entity portion of the
+ * block. Blocks that need custom configuration options can make use of the
+ * \Drupal\block\BlockBase::getConfiguration() and
+ * \Drupal\block\BlockBase::setConfigurationValue() methods to store persistent
+ * configuration data. See @link https://drupal.org/node/2168137 Block Plugin
+ * API in Drupal 8 @endlink for more details.
+ *
+ * The contents of a Block Plugin's annotation are based on the properties
+ * defined in \Drupal\block\Annotation\Block.
+ *
+ * The following is an example of a simple block class with annotations:
+ * @code
+ * namespace Drupal\mymodule\Plugin\Block;
+ * use Drupal\block\BlockBase;
+ *
+ * /**
+ *  * Provides an 'Example' block.
+ *  *
+ *  * @Block(
+ *  *   id = "example_block",
+ *  *   admin_label = @Translation("Example block"),
+ *  * )
+ *  * /
+ * class ExampleBlock extends BlockBase {
+ *
+ *   public function build() {
+ *     $build = array(
+ *       '#type' => 'markup',
+ *       '#markup' => t('Hello World'),
+ *     );
+ *   }
  *
- * See https://drupal.org/node/2168137
+ * }
+ * @endcode
  * @}
  */
 
+
 /**
  * @defgroup third_party REST and Application Integration
  * @{