Issue #1871762 by eojthebrave, jibran, xjm: Add detailed documentation...

Issue #1871762 by eojthebrave, jibran, xjm: Add detailed documentation explaining the block system's architecture.

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 {

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 {
 

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 {
 

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.
  */
 
 /**