diff --git a/core/modules/block/block.api.php b/core/modules/block/block.api.php
index 2d61bb0..da333f5 100644
--- a/core/modules/block/block.api.php
+++ b/core/modules/block/block.api.php
@@ -12,11 +12,13 @@
  * @{
  * Information about the classes and interfaces that make up the Block API.
  *
+ * @section sec_overview Overview
  * 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.
  *
+ * @section sec_requirements Basic requirements and example
  * To define a block in a module you need to:
  * - Define a Block plugin by creating a new class that implements the
  *   \Drupal\Core\Block\BlockPluginInterface, in namespace Plugin\Block under your
@@ -30,6 +32,38 @@
  *   @link annotation Annotations topic @endlink for more information about
  *   annotations.
  *
+ * Here's an example of a very simple block plugin class:
+ * @code
+ * namespace Drupal\examplemodule\Plugin\Block;
+ *
+ * use Drupal\Core\Block\BlockBase;
+ *
+ * /**
+ *  * An example block.
+ *  *
+ *  * @Block(
+ *  *   id = "example_block",
+ *  *   admin_label = @Translation("Example block")
+ *  * )
+ *  *\/
+ * class ExampleBlock extends BlockBase {
+ *   /**
+ *    * {@inheritDoc}
+ *    *
+ *    * Inherited from BlockPluginInterface, via BlockBase.
+ *    *\/
+ *   public function build() {
+ *     return [
+ *       '#type' => '#markup',
+ *       '#markup' => 'Example block',
+ *     ];
+ *   }
+ * }
+ * @endcode
+ *
+ * More examples are available at the links below.
+ *
+ * @section sec_extending Extending blocks with conditions and hooks
  * The Block API also makes use of Condition plugins, for conditional block
  * placement. Condition plugins have interface
  * \Drupal\Core\Condition\ConditionInterface, base class
@@ -43,7 +77,7 @@
  * - hook_block_view_BASE_BLOCK_ID_alter()
  * - hook_block_access()
  *
- * Further information and examples:
+ * @section sec_further_information Further information and examples
  * - \Drupal\system\Plugin\Block\SystemPoweredByBlock provides a simple example
  *   of defining a block.
  * - \Drupal\user\Plugin\Condition\UserRole is a straightforward example of a