Issue #2290285 by jhodgdon: Condition plugin classes need more links/docs.

core/lib/Drupal/Core/Condition/Annotation/Condition.php

@@ -9,7 +9,21 @@ namespace Drupal\Core\Condition\Annotation;
 use Drupal\Component\Annotation\Plugin;
 
 /**
- * Defines a condition annotation object.
+ * Defines a condition plugin annotation object.
+ *
+ * Condition plugins provide generalized conditions for use in other
+ * operations, such as conditional block placement.
+ *
+ * Plugin Namespace: Plugin\Condition
+ *
+ * For a working example, see \Drupal\user\Plugin\Condition\UserRole.
+ *
+ * @see \Drupal\Core\Condition\ConditionManager
+ * @see \Drupal\Core\Condition\ConditionInterface
+ * @see \Drupal\Core\Condition\ConditionPluginBase
+ * @see block_api
+ *
+ * @ingroup plugin_api
  *
  * @Annotation
  */

core/lib/Drupal/Core/Condition/ConditionInterface.php

@@ -30,6 +30,11 @@ use Drupal\Core\Plugin\PluginFormInterface;
  *
  * @see \Drupal\Core\TypedData\TypedDataManager::create()
  * @see \Drupal\Core\Executable\ExecutableInterface
+ * @see \Drupal\Core\Condition\ConditionManager
+ * @see \Drupal\Core\Condition\Annotation\Condition
+ * @see \Drupal\Core\Condition\ConditionPluginBase
+ *
+ * @ingroup plugin_api
  */
 interface ConditionInterface extends ExecutableInterface, PluginFormInterface, ConfigurablePluginInterface, PluginInspectionInterface {
 

core/lib/Drupal/Core/Condition/ConditionManager.php

@@ -16,6 +16,12 @@ use Drupal\Core\Plugin\DefaultPluginManager;
 
 /**
  * A plugin manager for condition plugins.
+ *
+ * @see \Drupal\Core\Condition\Annotation\Condition
+ * @see \Drupal\Core\Condition\ConditionInterface
+ * @see \Drupal\Core\Condition\ConditionPluginBase
+ *
+ * @ingroup plugin_api
  */
 class ConditionManager extends DefaultPluginManager implements ExecutableManagerInterface {
 

core/lib/Drupal/Core/Condition/ConditionPluginBase.php

@@ -11,6 +11,12 @@ use Drupal\Core\Executable\ExecutablePluginBase;
 
 /**
  * Provides a basis for fulfilling contexts for condition plugins.
+ *
+ * @see \Drupal\Core\Condition\Annotation\Condition
+ * @see \Drupal\Core\Condition\ConditionInterface
+ * @see \Drupal\Core\Condition\ConditionManager
+ *
+ * @ingroup plugin_api
  */
 abstract class ConditionPluginBase extends ExecutablePluginBase implements ConditionInterface {
 

core/modules/block/block.api.php

@@ -5,6 +5,56 @@
  * Hooks provided by the Block module.
  */
 
+/**
+ * @defgroup block_api Block API
+ * @{
+ * Information about the classes and interfaces that make up the Block API.
+ *
+ * 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, in namespace Plugin\Block under your
+ *   module namespace. For more information about creating plugins, 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.
+ *
+ * The Block API also makes use of Condition plugins, for conditional block
+ * placement. Condition plugins have interface
+ * \Drupal\Core\Condition\ConditionInterface, base class
+ * \Drupal\Core\Condition\ConditionPluginBase, and go in plugin namespace
+ * Plugin\Condition. Again, see the Plugin API and Annotations topics for
+ * details of how to create a plugin class and annotate it.
+ *
+ * There are also several block-related hooks, which allow you to affect
+ * the content and access permissions for blocks:
+ * - hook_block_view_alter()
+ * - hook_block_view_BASE_BLOCK_ID_alter()
+ * - hook_block_access()
+ *
+ * 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
+ *   block placement condition plugin.
+ * - \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 for Developers project also provides a Block example in
+ *   https://drupal.org/project/examples.
+ * @}
+ */
+
 /**
  * @addtogroup hooks
  * @{
@@ -35,6 +85,7 @@
  *   The block plugin instance.
  *
  * @see hook_block_view_BASE_BLOCK_ID_alter()
+ * @ingroup block_api
  */
 function hook_block_view_alter(array &$build, \Drupal\block\BlockPluginInterface $block) {
   // Remove the contextual links on all blocks that provide them.
@@ -62,6 +113,7 @@ function hook_block_view_alter(array &$build, \Drupal\block\BlockPluginInterface
  *   The block plugin instance.
  *
  * @see hook_block_view_alter()
+ * @ingroup block_api
  */
 function hook_block_view_BASE_BLOCK_ID_alter(array &$build, \Drupal\block\BlockPluginInterface $block) {
   // Change the title of the specific block.
@@ -90,6 +142,7 @@ function hook_block_view_BASE_BLOCK_ID_alter(array &$build, \Drupal\block\BlockP
  *
  * @see \Drupal\Core\Entity\EntityAccessController::access()
  * @see \Drupal\block\BlockAccessController::checkAccess()
+ * @ingroup block_api
  */
 function hook_block_access(\Drupal\block\Entity\Block $block, $operation, \Drupal\user\Entity\User $account, $langcode) {
   // Example code that would prevent displaying the 'Powered by Drupal' block in

core/modules/system/core.api.php

@@ -66,39 +66,6 @@
  * - @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.
- *
- * 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.
- */
-
 /**
  * @defgroup third_party REST and Application Integration
  * @{