From 633dd952f790ff513bf0ad6972ab86b749b85f12 Mon Sep 17 00:00:00 2001
From: webchick <webchick@24967.no-reply.drupal.org>
Date: Tue, 29 Apr 2014 13:01:32 -0700
Subject: [PATCH] Issue #2216561 by jhodgdon: Fill in @defgroup/topic docs for
Extending Drupal.
---
core/includes/module.inc | 61 +++++++++++++++++++++++---------
core/modules/system/core.api.php | 56 ++++++++++++++++++++++++++---
2 files changed, 95 insertions(+), 22 deletions(-)
diff --git a/core/includes/module.inc b/core/includes/module.inc
index d2cab6aad7da..93dd9248a76d 100644
--- a/core/includes/module.inc
+++ b/core/includes/module.inc
@@ -178,31 +178,58 @@ function module_uninstall($module_list = array(), $uninstall_dependents = TRUE)
/**
* @defgroup hooks Hooks
* @{
- * Allow modules to interact with the Drupal core.
+ * Define functions that alter the behavior of Drupal core.
*
- * Drupal's module system is based on the concept of "hooks". A hook is a PHP
- * function that is named foo_bar(), where "foo" is the name of the module
- * (whose filename is thus foo.module) and "bar" is the name of the hook. Each
- * hook has a defined set of parameters and a specified result type.
+ * One way for modules to alter the core behavior of Drupal (or another module)
+ * is to use hooks. Hooks are specially-named functions that a module defines
+ * (this is known as "implementing the hook"), which are discovered and called
+ * at specific times to alter or add to the base behavior or data (this is
+ * known as "invoking the hook"). Each hook has a name (example:
+ * hook_batch_alter()), a defined set of parameters, and a defined return value.
+ * Your modules can implement hooks that are defined by Drupal core or other
+ * modules that they interact with. Your modules can also define their own
+ * hooks, in order to let other modules interact with them.
*
- * To extend Drupal, a module need simply implement a hook. When Drupal wishes
- * to allow intervention from modules, it determines which modules implement a
- * hook and calls that hook in all enabled modules that implement it.
+ * To implement a hook:
+ * - Locate the documentation for the hook. Hooks are documented in *.api.php
+ * files, by defining functions whose name starts with "hook_" (these
+ * files and their functions are never loaded by Drupal -- they exist solely
+ * for documentation). The function should have a documentation header, as
+ * well as a sample function body. For example, in the core file
+ * system.api.php, you can find hooks such as hook_batch_alter(). Also, if
+ * you are viewing this documentation on an API reference site, the Core
+ * hooks will be listed in this topic.
+ * - Copy the function to your module's .module file.
+ * - Change the name of the function, substituting your module's short name
+ * (name of the module's directory, and .info.yml file without the extension)
+ * for the "hook" part of the sample function name. For instance, to implemnt
+ * hook_batch_alter(), you would rename it to my_module_batch_alter().
+ * - Edit the documentation for the function (normally, your implementation
+ * should just have one line saying "Implements hook_batch_alter().").
+ * - Edit the body of the function, substituting in what you need your module
+ * to do.
*
- * The available hooks to implement are explained here in the Hooks section of
- * the developer documentation. The string "hook" is used as a placeholder for
- * the module name in the hook definitions. For example, if the module file is
- * called example.module, then hook_help() as implemented by that module would
- * be defined as example_help().
+ * To define a hook:
+ * - Choose a unique name for your hook. It should start with "hook_", followed
+ * by your module's short name.
+ * - Provide documentation in a *.api.php file in your module's main
+ * directory. See the "implementing" section above for details of what this
+ * should contain (parameters, return value, and sample function body).
+ * - Invoke the hook in your module's code.
*
- * The example functions included are not part of the Drupal core, they are
- * just models that you can modify. Only the hooks implemented within modules
- * are executed when running Drupal.
+ * To invoke a hook, use methods on
+ * \Drupal\Core\Extension\ModuleHandlerInterface such as alter(), invoke(),
+ * and invokeAll(). You can obtain a module handler by calling
+ * \Drupal::moduleHandler(), or getting the 'module_handler' service on an
+ * injected container.
*
+ * @see extending
* @see themeable
* @see callbacks
+ * @see \Drupal\Core\Extension\ModuleHandlerInterface
+ * @see \Drupal::moduleHandler()
*
- * @} End of "defgroup hooks".
+ * @}
*/
/**
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 1ecc9c1a744d..01592d7a744a 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -19,7 +19,7 @@
*
* - @link architecture Drupal's architecture @endlink
* - @link oo_conventions Object-oriented conventions used in Drupal @endlink
- * - @link extending Extending Drupal @endlink
+ * - @link extending Extending and altering Drupal @endlink
* - @link best_practices Security and best practices @endlink
*
* @section interface User interface
@@ -452,15 +452,61 @@
*/
/**
- * @defgroup extending Extending Drupal
+ * @defgroup extending Extending and altering Drupal
* @{
- * Overview of hooks, plugins, annotations, event listeners, and services.
+ * Overview of add-ons and alteration methods for Drupal.
+ *
+ * Drupal's core behavior can be extended and altered via these three basic
+ * types of add-ons:
+ * - Themes: Themes alter the appearance of Drupal sites. They can include
+ * template files, which alter the HTML markup and other raw output of the
+ * site; CSS files, which alter the styling applied to the HTML; and
+ * JavaScript, Flash, images, and other files. For more information, see the
+ * @link theme_render Theme system and render API topic @endlink and
+ * https://drupal.org/theme-guide/8
+ * - Modules: Modules add to or alter the behavior and functionality of Drupal,
+ * by using one or more of the methods listed below. For more information
+ * about creating modules, see https://drupal.org/developing/modules/8
+ * - Installation profiles: Installation profiles can be used to
+ * create distributions, which are complete specific-purpose packages of
+ * Drupal including additional modules, themes, and data. For more
+ * information, see https://drupal.org/documentation/build/distributions.
+ *
+ * Here is a list of the ways that modules can alter or extend Drupal's core
+ * behavior, or the behavior of other modules:
+ * - Hooks: Specially-named functions that a module defines, which are
+ * discovered and called at specific times, usually to alter behavior or data.
+ * See the @link hooks Hooks topic @endlink for more information.
+ * - Plugins: Classes that a module defines, which are discovered and
+ * instantiated at specific times to add functionality. See the
+ * @link plugins Plugin API topic @endlink for more information.
+ * - Entities: Special plugins that define entity types for storing new types
+ * of content or configuration in Drupal. See the
+ * @link entity_api Entity API topic @endlink for more information.
+ * - Services: Classes that perform basic operations within Drupal, such as
+ * accessing the database and sending e-mail. See the
+ * @link container Dependency Injection Container and Services topic @endlink
+ * for more information.
+ * - Routing: Providing or altering "routes", which are URLs that Drupal
+ * responds to, or altering routing behavior with event listener classes.
+ * See the @link menu Routing and menu topic @endlink for more information.
+ * @}
+ */
+
+/**
+ * @defgroup plugins Plugin API
+ * @{
+ * Overview of the Plugin API
*
* @todo write this
*
* Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic. This should be
- * high-level and link to more detailed topics.
+ * classes, and interfaces need to be added to this topic.
+ *
+ * See https://drupal.org/developing/api/8/plugins and links therein for
+ * references. This should be an overview and link to details.
+ *
+ * @see annotation
* @}
*/
--
GitLab