diff --git a/core/lib/Drupal/Core/Config/Config.php b/core/lib/Drupal/Core/Config/Config.php
index 76a5b333e8cc631758ad9e6c29343f462f26d4f9..5360edd0d9c88bf75b5100445941c3efa1463a8b 100644
--- a/core/lib/Drupal/Core/Config/Config.php
+++ b/core/lib/Drupal/Core/Config/Config.php
@@ -17,6 +17,8 @@
* specific configuration object, including support for runtime overrides. The
* overrides are handled on top of the stored configuration so they are not
* saved back to storage.
+ *
+ * @ingroup config_api
*/
class Config extends StorableConfigBase {
diff --git a/core/lib/Drupal/Core/Config/Entity/ConfigEntityBase.php b/core/lib/Drupal/Core/Config/Entity/ConfigEntityBase.php
index d604caf58a665f2df62b3309deee922715ce4e18..e020a2ebedd56edb3d98c9751ea5554a99fff2d5 100644
--- a/core/lib/Drupal/Core/Config/Entity/ConfigEntityBase.php
+++ b/core/lib/Drupal/Core/Config/Entity/ConfigEntityBase.php
@@ -17,6 +17,8 @@
/**
* Defines a base configuration entity class.
+ *
+ * @ingroup entity_api
*/
abstract class ConfigEntityBase extends Entity implements ConfigEntityInterface {
diff --git a/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php b/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php
index f15a92bd20979f70e4f0098e2e24685f398f2e2f..586d6dff1eb1990aded9d5b87c1f310a4c618526 100644
--- a/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php
+++ b/core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php
@@ -11,6 +11,9 @@
/**
* Defines the interface common for all configuration entities.
+ *
+ * @ingroup config_api
+ * @ingroup entity_api
*/
interface ConfigEntityInterface extends EntityInterface {
diff --git a/core/lib/Drupal/Core/Config/Entity/ConfigEntityListBuilder.php b/core/lib/Drupal/Core/Config/Entity/ConfigEntityListBuilder.php
index 2bf8807a0c8566a5e89c0f27e991f8c91a3e7001..01fb7dd6b4ce9bd7098df77d59c1f46539ac126b 100644
--- a/core/lib/Drupal/Core/Config/Entity/ConfigEntityListBuilder.php
+++ b/core/lib/Drupal/Core/Config/Entity/ConfigEntityListBuilder.php
@@ -12,6 +12,8 @@
/**
* Defines the default class to build a listing of configuration entities.
+ *
+ * @ingroup entity_api
*/
class ConfigEntityListBuilder extends EntityListBuilder {
diff --git a/core/lib/Drupal/Core/Entity/EntityConfirmFormBase.php b/core/lib/Drupal/Core/Entity/EntityConfirmFormBase.php
index 564fa88f3dfb1353d5d1764d2e50451a72b6f8d4..a86d646f2d270b362d9eaf61bf37d1ea4b0390a8 100644
--- a/core/lib/Drupal/Core/Entity/EntityConfirmFormBase.php
+++ b/core/lib/Drupal/Core/Entity/EntityConfirmFormBase.php
@@ -13,6 +13,8 @@
/**
* Provides a generic base class for an entity-based confirmation form.
+ *
+ * @ingroup entity_api
*/
abstract class EntityConfirmFormBase extends EntityForm implements ConfirmFormInterface {
diff --git a/core/lib/Drupal/Core/Entity/EntityForm.php b/core/lib/Drupal/Core/Entity/EntityForm.php
index 9f5969420624502158afa8cb9828b8fdc5edeee9..dcb9aaeccde56b51240bf475736d4b6afd1f2dec 100644
--- a/core/lib/Drupal/Core/Entity/EntityForm.php
+++ b/core/lib/Drupal/Core/Entity/EntityForm.php
@@ -13,6 +13,8 @@
/**
* Base class for entity forms.
+ *
+ * @ingroup entity_api
*/
class EntityForm extends FormBase implements EntityFormInterface {
diff --git a/core/lib/Drupal/Core/State/StateInterface.php b/core/lib/Drupal/Core/State/StateInterface.php
index abfd2899d5362bb2a5f13557a95a94f32c5b0bed..b6f08a9f1618aed8602604bbe30cf9e555ecc289 100644
--- a/core/lib/Drupal/Core/State/StateInterface.php
+++ b/core/lib/Drupal/Core/State/StateInterface.php
@@ -9,6 +9,8 @@
/**
* Defines the interface for the state system.
+ *
+ * @ingroup state_api
*/
interface StateInterface {
diff --git a/core/modules/config/config.api.php b/core/modules/config/config.api.php
deleted file mode 100644
index 7b06336bf3923220fdff6e7c85a97de647930247..0000000000000000000000000000000000000000
--- a/core/modules/config/config.api.php
+++ /dev/null
@@ -1,13 +0,0 @@
-<?php
-
-/**
- * @file
- * Hooks provided by the Configuration module.
- */
-
-/**
- * @defgroup config_hooks Configuration system hooks
- * @{
- * @todo Overall description of the configuration system.
- * @}
- */
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 01592d7a744aead3fbbb78c716f3b76d0e1e9dc0..c8a5edec012807b32ee11cdae599e10ebbc30d90 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -31,8 +31,9 @@
*
* @section store_retrieve Storing and retrieving data
*
- * - @link config_state Configuration and State systems @endlink
* - @link entity_api Entities @endlink
+ * - @link config_api Configuration API @endlink
+ * - @link state_api State API @endlink
* - @link field Fields @endlink
* - @link node_overview Node system @endlink
* - @link views_overview Views @endlink
@@ -88,22 +89,156 @@
* @}
*/
-
/**
- * @defgroup config_state Configuration and State Systems
+ * @defgroup state_api State API
* @{
- * Information about the Configuration system and the State system.
+ * Information about the State API.
*
- * @todo write this
+ * The State API is one of several methods in Drupal for storing information.
+ * See @link architecture Drupal's architecture topic @endlink for an
+ * overview of the different types of information.
*
- * This topic needs to describe simple configuration, configuration entities,
- * and the state system, at least at an overview level, and link to more
- * information (either drupal.org or more detailed topics in the API docs).
+ * The basic entry point into the State API is \Drupal::state(), which returns
+ * an object of class \Drupal\Core\State\StateInterface. This class has
+ * methods for storing and retrieving state information; each piece of state
+ * information is associated with a string-valued key. Example:
+ * @code
+ * // Get the state class.
+ * $state = \Drupal::state();
+ * // Find out when cron was last run; the key is 'system.cron_last'.
+ * $time = $state->get('system.cron_last');
+ * // Set the cron run time to the current request time.
+ * $state->set('system_cron_last', REQUEST_TIME);
+ * @endcode
*
- * See https://drupal.org/node/1667894
+ * For more on the State API, see https://drupal.org/developing/api/8/state
+ * @}
+ */
+
+/**
+ * @defgroup config_api Configuration API
+ * @{
+ * Information about the Configuration API.
+ *
+ * The Configuration API is one of several methods in Drupal for storing
+ * information. See @link architecture Drupal's architecture topic @endlink for
+ * an overview of the different types of information. The sections below have
+ * more information about the configuration API; see
+ * https://drupal.org/developing/api/8/configuration for more details.
+ *
+ * @section sec_storage Configuration storage
+ * In Drupal, there is a concept of the "active" configuration, which is the
+ * configuration that is currently in use for a site. The storage used for the
+ * active configuration is configurable: it could be in the database, in files
+ * in a particular directory, or in other storage backends; the default storage
+ * is in the database. Module developers must use the configuration API to
+ * access the active configuration, rather than being concerned about the
+ * details of where and how it is stored.
+ *
+ * Configuration is divided into individual objects, each of which has a
+ * unique name or key. Some modules will have only one configuration object,
+ * typically called 'mymodule.settings'; some modules will have many. Within
+ * a configuration object, configuration settings have data types (integer,
+ * string, Boolean, etc.) and settings can also exist in a nested hierarchy,
+ * known as a "mapping".
+ *
+ * @section sec_yaml Configuration YAML files
+ * Whether or not configuration files are being used for the active
+ * configuration storage on a particular site, configuration files are always
+ * used for:
+ * - Defining the default configuration for a module, which is imported to the
+ * active storage when the module is enabled. Note that changes to this
+ * default configuration after a module is already enabled have no effect;
+ * to make a configuration change after a module is enabled, you would need
+ * to uninstall/reinstall or use a hook_update_N() function.
+ * - Exporting and importing configuration.
+ *
+ * The file storage format for configuration information in Drupal is @link
+ * http://en.wikipedia.org/wiki/YAML YAML files. @endlink Configuration is
+ * divided into files, each containing one configuration object. The file name
+ * for a configuration object is equal to the unique name of the configuration,
+ * with a '.yml' extension. The default configuration files for each module are
+ * placed in the config/install directory under the top-level module directory,
+ * so look there in most Core modules for examples.
+ *
+ * Each configuration file has a specific structure, which is expressed as a
+ * YAML-based configuration schema. The configuration schema details the
+ * structure of the configuration, its data types, and which of its values need
+ * to be translatable. Each module needs to define its configuration schema in
+ * files in the config/schema directory under the top-level module directory, so
+ * look there in most Core modules for examples.
+ *
+ * @section sec_simple Simple configuration
+ * The simple configuration API should be used for information that will always
+ * have exactly one copy or version. For instance, if your module has a
+ * setting that is either on or off, then this is only defined once, and it
+ * would be a Boolean-valued simple configuration setting.
+ *
+ * The first task in using the simple configuration API is to define the
+ * configuration file structure, file name, and schema of your settings (see
+ * @ref sec_yaml above). Once you have done that, you can retrieve the
+ * active configuration object that corresponds to configuration file
+ * mymodule.foo.yml with a call to:
+ * @code
+ * $config = \Drupal::config('mymodule.foo');
+ * @endcode
*
- * Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic.
+ * This will be an object of class \Drupal\Core\Config\Config, which has methods
+ * for getting and setting configuration information. For instance, if your
+ * YAML file structure looks like this:
+ * @code
+ * enabled: '0'
+ * bar:
+ * baz: 'string1'
+ * boo: 34
+ * @endcode
+ * you can make calls such as:
+ * @code
+ * // Get a single value.
+ * $enabled = $config->get('enabled');
+ * // Get an associative array.
+ * $bar = $config->get('bar');
+ * // Get one element of the array.
+ * $bar_baz = $config->get('bar.baz');
+ * // Update a value. Nesting works the same as get().
+ * $config->set('bar.baz', 'string2');
+ * // Nothing actually happens with set() until you call save().
+ * $config->save();
+ * @endcode
+ *
+ * @section sec_entity Configuration entities
+ * In contrast to the simple configuration settings described in the previous
+ * section, if your module allows users to create zero or more items (where
+ * "items" are things like content type definitions, view definitions, and the
+ * like), then you need to define a configuration entity type to store your
+ * configuration. Creating an entity type, loading entites, and querying them
+ * are outlined in the @link entity_api Entity API topic. @endlink Here are a
+ * few additional steps and notes specific to configuration entities:
+ * - For examples, look for classes that implement
+ * \Drupal\Core\Config\Entity\ConfigEntityInterface -- one good example is
+ * the \Drupal\user\Entity\Role entity type.
+ * - In the entity type annotation, you will need to define a 'config_prefix'
+ * string. When Drupal stores a configuration item, it will be given a name
+ * composed of your module name, your chosen config prefix, and the ID of
+ * the individual item, separated by '.'. For example, in the Role entity,
+ * the config prefix is 'role', so one configuration item might be named
+ * user.role.anonymous, with configuration file user.role.anonymous.yml.
+ * - You will need to define the schema for your configuration in your
+ * modulename.schema.yml file, with an entry for 'modulename.config_prefix.*'.
+ * For example, for the Role entity, the file user.schema.yml has an entry
+ * user.role.*; see @ref sec_yaml above for more information.
+ * - Your module may also provide a few configuration items to be installed by
+ * default, by adding configuration files to the module's config/install
+ * directory; see @ref sec_yaml above for more information.
+ * - Some configuration entities have dependencies on other configuration
+ * entities, and module developers need to consider this so that configuration
+ * can be imported, uninstalled, and synchronized in the right order. For
+ * example, a field display configuration entity would need to depend on
+ * field instance configuration, which depends on field and bundle
+ * configuration. Configuration entity classes expose dependencies by
+ * overriding the
+ * \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies()
+ * method.
* @}
*/
@@ -112,14 +247,71 @@
* @{
* Describes how to define and manipulate content and configuration entities.
*
- * @todo write this
+ * @todo Add an overview here, describing what an entity is, bundles, entity
+ * types, etc. at an overview level. And link to more detailed documentation:
+ * https://drupal.org/developing/api/entity
+ *
+ * @section types Types of entities
+ * Entities can be used to store content or configuration information. See the
+ * @link architecture Drupal's architecture topic @endlink for an overview of
+ * the different types of information, and the
+ * @link config_api Configuration API topic @endlink for more about the
+ * configuration API. Defining and manipulating content and configuration
+ * entities is very similar, and this is described in the sections below.
+ *
+ * @section define Defining an entity type
+ *
+ * @todo This section was written for Config entities. Add information about
+ * content entities to each item, and add additional items that are relevant
+ * to content entities, making sure to say they are not needed for config
+ * entities, such as view page controllers, etc.
+ *
+ * Here are the steps to follow to define a new entity type:
+ * - Choose a unique machine name, or ID, for your entity type. This normally
+ * starts with (or is the same as) your module's machine name. It should be
+ * as short as possible, and may not exceed 32 characters.
+ * - Define an interface for your entity's get/set methods, extending either
+ * \Drupal\Core\Config\Entity\ConfigEntityInterface or [content entity
+ * interface].
+ * - Define a class for your entity, implementing your interface and extending
+ * either \Drupal\Core\Config\Entity\ConfigEntityBase or [content entity
+ * class] , with annotation for \@ConfigEntityType or [content entity
+ * annotation] in its documentation block.
+ * - The 'id' annotation gives the entity type ID, and the 'label' annotation
+ * gives the human-readable name of the entity type.
+ * - The annotation will refer to several controller classes, which you will
+ * also need to define:
+ * - list_builder: Define a class that extends
+ * \Drupal\Core\Config\Entity\ConfigEntityListBuilder or [content entity
+ list builder], to provide an administrative overview for your entities.
+ * - add and edit forms, or default form: Define a class (or two) that
+ * extend(s) \Drupal\Core\Entity\EntityForm to provide add and edit forms
+ * for your entities.
+ * - delete form: Define a class that extends
+ * \Drupal\Core\Entity\EntityConfirmFormBase to provide a delete
+ * confirmation form for your entities.
+ * - access: If your configuration entity has complex permissions, you might
+ * need an access controller, implementing
+ * \Drupal\Core\Entity\EntityAccessControllerInterface, but most entities
+ * can just use the 'admin_permission' annotation instead.
+ *
+ * @section load_query Loading and querying entities
+ * To load entities, use the entity storage manager, which is a class
+ * implementing \Drupal\Core\Entity\EntityStorageInterface that you can
+ * retrieve with:
+ * @code
+ * $storage = \Drupal::entityManager()->getStorage('your_entity_type');
+ * @endcode
*
- * Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic. Should describe
- * bundles, entity types, configuration vs. content entities, etc. at an
- * overview level. And link to more detailed documentation.
+ * To query to find entities to load, use an entity query, which is a class
+ * implementing \Drupal\Core\Entity\Query\QueryInterface that you can retrieve
+ * with:
+ * @code
+ * $storage = \Drupal::entityQuery('your_entity_type');
+ * @endcode
*
- * See https://drupal.org/developing/api/entity
+ * @todo Add additional relevant classes and interfaces to this topic using
+ * ingroup.
* @}
*/
@@ -448,6 +640,30 @@
* classes, and interfaces need to be added to this topic.
*
* Should include: modules, info.yml files, location of files, etc.
+ *
+ * @section Types of information in Drupal
+ * Drupal has several distinct types of information, each with its own methods
+ * for storage and retrieval:
+ * - Content: Information meant to be displayed on your site: articles, basic
+ * pages, images, files, custom blocks, etc. Content is stored and accessed
+ * using @link entity_api Entities @endlink.
+ * - Session: Information about individual users' interactions with the site,
+ * such as whether they are logged in. This is really "state" information, but
+ * it is not stored the same way so it's a separate type here. Session
+ * information is managed ...
+ * - State: Information of a temporary nature, generally machine-generated and
+ * not human-edited, about the current state of your site. Examples: the time
+ * when Cron was last run, whether node access permissions need rebuilding,
+ * etc. See @link state_api the State API topic @endlink for more information.
+ * - Configuration: Information about your site that is generally (or at least
+ * can be) human-edited, but is not Content, and is meant to be relatively
+ * permanent. Examples: the name of your site, the content types and views
+ * you have defined, etc. See
+ * @link config_api the Configuration API topic @endlink for more information.
+ *
+ * @todo Add something relevant to the list item about sessions.
+ * @todo Add some information about Settings, the key-value store in general,
+ * and maybe the cache to this list (not sure if cache belongs here?).
* @}
*/