Issue #2216529 by jhodgdon: Fill in topic/@defgroup docs for Config and State System.

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 {
 

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 {
 

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 {
 

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 {
 

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 {
 

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 {
 

core/lib/Drupal/Core/State/StateInterface.php

@@ -9,6 +9,8 @@
 
 /**
  * Defines the interface for the state system.
+ *
+ * @ingroup state_api
  */
 interface StateInterface {
 

core/modules/config/config.api.php

-<?php
-
-/**
- * @file
- * Hooks provided by the Configuration module.
- */
-
-/**
- * @defgroup config_hooks Configuration system hooks
- * @{
- * @todo Overall description of the configuration system.
- * @}
- */

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?).
  * @}
  */