From 5a0893fd2a74bb3f0945f0fef78b99ed80968e35 Mon Sep 17 00:00:00 2001
From: webchick <drupal@webchick.net>
Date: Mon, 16 Jun 2014 10:02:24 -0700
Subject: [PATCH] Issue #2216553 by jhodgdon, fago: Fill in @defgroup/topic
docs for Typed Data.
---
.../Core/TypedData/Annotation/DataType.php | 2 +
.../ComplexDataDefinitionInterface.php | 2 +
.../Core/TypedData/ComplexDataInterface.php | 2 +
.../TypedData/DataDefinitionInterface.php | 2 +
.../DataReferenceDefinitionInterface.php | 2 +
.../TypedData/ListDataDefinitionInterface.php | 2 +
.../Drupal/Core/TypedData/ListInterface.php | 2 +
.../TypedData/Plugin/DataType/ItemList.php | 2 +
.../Core/TypedData/Plugin/DataType/Map.php | 2 +
.../Core/TypedData/PrimitiveInterface.php | 2 +
.../Core/TypedData/Type/BinaryInterface.php | 4 +-
.../Core/TypedData/Type/DateTimeInterface.php | 2 +
.../Core/TypedData/Type/DurationInterface.php | 2 +
.../Core/TypedData/Type/FloatInterface.php | 2 +
.../Core/TypedData/Type/IntegerInterface.php | 2 +
.../Core/TypedData/Type/StringInterface.php | 2 +
.../Core/TypedData/Type/UriInterface.php | 2 +
core/lib/Drupal/Core/TypedData/TypedData.php | 2 +
.../Core/TypedData/TypedDataInterface.php | 2 +
core/modules/system/core.api.php | 62 ++++++++++++++++---
20 files changed, 93 insertions(+), 9 deletions(-)
diff --git a/core/lib/Drupal/Core/TypedData/Annotation/DataType.php b/core/lib/Drupal/Core/TypedData/Annotation/DataType.php
index 880ec65671fc..332c3edb6bbc 100644
--- a/core/lib/Drupal/Core/TypedData/Annotation/DataType.php
+++ b/core/lib/Drupal/Core/TypedData/Annotation/DataType.php
@@ -32,6 +32,8 @@
* @see \Drupal\Core\TypedData\TypedDataManager::create()
* @see hook_data_type_info_alter()
*
+ * @ingroup typed_data
+ *
* @Annotation
*/
class DataType extends Plugin {
diff --git a/core/lib/Drupal/Core/TypedData/ComplexDataDefinitionInterface.php b/core/lib/Drupal/Core/TypedData/ComplexDataDefinitionInterface.php
index efa5fdfeafb0..5cc15068e95b 100644
--- a/core/lib/Drupal/Core/TypedData/ComplexDataDefinitionInterface.php
+++ b/core/lib/Drupal/Core/TypedData/ComplexDataDefinitionInterface.php
@@ -11,6 +11,8 @@
* Interface for complex data definitions.
*
* @see \Drupal\Core\TypedData\ComplexDataInterface
+ *
+ * @ingroup typed_data
*/
interface ComplexDataDefinitionInterface extends DataDefinitionInterface {
diff --git a/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php b/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php
index 39ed9cef6f65..923090ebf824 100644
--- a/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php
+++ b/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php
@@ -20,6 +20,8 @@
* IteratorAggregate or Iterator before this interface in the implements clause.
*
* @see \Drupal\Core\TypedData\ComplexDataDefinitionInterface
+ *
+ * @ingroup typed_data
*/
interface ComplexDataInterface extends \Traversable, TypedDataInterface {
diff --git a/core/lib/Drupal/Core/TypedData/DataDefinitionInterface.php b/core/lib/Drupal/Core/TypedData/DataDefinitionInterface.php
index 53d6a567c70d..1b1aecb1a844 100644
--- a/core/lib/Drupal/Core/TypedData/DataDefinitionInterface.php
+++ b/core/lib/Drupal/Core/TypedData/DataDefinitionInterface.php
@@ -23,6 +23,8 @@
* @see \Drupal\Core\TypedData\ComplexDataDefinitionInterface
* @see \Drupal\Core\TypedData\DataReferenceDefinitionInterface
* @see \Drupal\Core\TypedData\TypedDataInterface
+ *
+ * @ingroup typed_data
*/
interface DataDefinitionInterface {
diff --git a/core/lib/Drupal/Core/TypedData/DataReferenceDefinitionInterface.php b/core/lib/Drupal/Core/TypedData/DataReferenceDefinitionInterface.php
index 334cc9bdb356..a7f2df59d725 100644
--- a/core/lib/Drupal/Core/TypedData/DataReferenceDefinitionInterface.php
+++ b/core/lib/Drupal/Core/TypedData/DataReferenceDefinitionInterface.php
@@ -12,6 +12,8 @@
*
* @see \Drupal\Core\TypedData\DataReferenceDefinition
* @see \Drupal\Core\TypedData\DataReferenceInterface
+ *
+ * @ingroup typed_data
*/
interface DataReferenceDefinitionInterface extends DataDefinitionInterface {
diff --git a/core/lib/Drupal/Core/TypedData/ListDataDefinitionInterface.php b/core/lib/Drupal/Core/TypedData/ListDataDefinitionInterface.php
index 67d2cc1c5e01..c506fe7eeca1 100644
--- a/core/lib/Drupal/Core/TypedData/ListDataDefinitionInterface.php
+++ b/core/lib/Drupal/Core/TypedData/ListDataDefinitionInterface.php
@@ -15,6 +15,8 @@
*
* @see \Drupal\Core\TypedData\ListDefinition
* @see \Drupal\Core\TypedData\ListInterface
+ *
+ * @ingroup typed_data
*/
interface ListDataDefinitionInterface extends DataDefinitionInterface {
diff --git a/core/lib/Drupal/Core/TypedData/ListInterface.php b/core/lib/Drupal/Core/TypedData/ListInterface.php
index e8803b311b97..bf70d6f56b62 100644
--- a/core/lib/Drupal/Core/TypedData/ListInterface.php
+++ b/core/lib/Drupal/Core/TypedData/ListInterface.php
@@ -17,6 +17,8 @@
* IteratorAggregate or Iterator before this interface in the implements clause.
*
* @see \Drupal\Core\TypedData\ListDefinitionInterface
+ *
+ * @ingroup typed_data
*/
interface ListInterface extends TypedDataInterface, \ArrayAccess, \Countable, \Traversable {
diff --git a/core/lib/Drupal/Core/TypedData/Plugin/DataType/ItemList.php b/core/lib/Drupal/Core/TypedData/Plugin/DataType/ItemList.php
index 25b39f8299a9..54f36484504e 100644
--- a/core/lib/Drupal/Core/TypedData/Plugin/DataType/ItemList.php
+++ b/core/lib/Drupal/Core/TypedData/Plugin/DataType/ItemList.php
@@ -20,6 +20,8 @@
* Drupal\Core\TypedData\Annotation\DataType.
* Note: The class cannot be called "List" as list is a reserved PHP keyword.
*
+ * @ingroup typed_data
+ *
* @DataType(
* id = "list",
* label = @Translation("List of items"),
diff --git a/core/lib/Drupal/Core/TypedData/Plugin/DataType/Map.php b/core/lib/Drupal/Core/TypedData/Plugin/DataType/Map.php
index 481eebe6d06b..bc699ccb75f9 100644
--- a/core/lib/Drupal/Core/TypedData/Plugin/DataType/Map.php
+++ b/core/lib/Drupal/Core/TypedData/Plugin/DataType/Map.php
@@ -20,6 +20,8 @@
* By default there is no metadata for contained properties. Extending classes
* may want to override Map::getPropertyDefinitions() to define it.
*
+ * @ingroup typed_data
+ *
* @DataType(
* id = "map",
* label = @Translation("Map"),
diff --git a/core/lib/Drupal/Core/TypedData/PrimitiveInterface.php b/core/lib/Drupal/Core/TypedData/PrimitiveInterface.php
index 01ad0d9aed1f..f392ec6f5012 100644
--- a/core/lib/Drupal/Core/TypedData/PrimitiveInterface.php
+++ b/core/lib/Drupal/Core/TypedData/PrimitiveInterface.php
@@ -9,6 +9,8 @@
/**
* Interface for primitive data.
+ *
+ * @ingroup typed_data
*/
interface PrimitiveInterface {
diff --git a/core/lib/Drupal/Core/TypedData/Type/BinaryInterface.php b/core/lib/Drupal/Core/TypedData/Type/BinaryInterface.php
index 6f4b487216ae..ec866f8b2874 100644
--- a/core/lib/Drupal/Core/TypedData/Type/BinaryInterface.php
+++ b/core/lib/Drupal/Core/TypedData/Type/BinaryInterface.php
@@ -13,8 +13,10 @@
* Interface for binary data.
*
* The plain value of binary data is a PHP file resource, see
- * http://php.net/manual/en/language.types.resource.php. For setting the value
+ * http://php.net/manual/language.types.resource.php. For setting the value
* a PHP file resource or a (absolute) stream resource URI may be passed.
+ *
+ * @ingroup typed_data
*/
interface BinaryInterface extends PrimitiveInterface {
diff --git a/core/lib/Drupal/Core/TypedData/Type/DateTimeInterface.php b/core/lib/Drupal/Core/TypedData/Type/DateTimeInterface.php
index 3bbcd22e143d..e8d17c536919 100644
--- a/core/lib/Drupal/Core/TypedData/Type/DateTimeInterface.php
+++ b/core/lib/Drupal/Core/TypedData/Type/DateTimeInterface.php
@@ -11,6 +11,8 @@
/**
* Interface for dates, optionally including a time.
+ *
+ * @ingroup typed_data
*/
interface DateTimeInterface {
diff --git a/core/lib/Drupal/Core/TypedData/Type/DurationInterface.php b/core/lib/Drupal/Core/TypedData/Type/DurationInterface.php
index 9f8e176ebd75..70329648e0db 100644
--- a/core/lib/Drupal/Core/TypedData/Type/DurationInterface.php
+++ b/core/lib/Drupal/Core/TypedData/Type/DurationInterface.php
@@ -9,6 +9,8 @@
/**
* Interface for durations.
+ *
+ * @ingroup typed_data
*/
interface DurationInterface {
diff --git a/core/lib/Drupal/Core/TypedData/Type/FloatInterface.php b/core/lib/Drupal/Core/TypedData/Type/FloatInterface.php
index 643fcbe33b18..6cbb91af0450 100644
--- a/core/lib/Drupal/Core/TypedData/Type/FloatInterface.php
+++ b/core/lib/Drupal/Core/TypedData/Type/FloatInterface.php
@@ -14,6 +14,8 @@
*
* The plain value of a float is a regular PHP float. For setting the value
* any PHP variable that casts to a float may be passed.
+ *
+ * @ingroup typed_data
*/
interface FloatInterface extends PrimitiveInterface {
diff --git a/core/lib/Drupal/Core/TypedData/Type/IntegerInterface.php b/core/lib/Drupal/Core/TypedData/Type/IntegerInterface.php
index 4554a304fc84..6c9368b80124 100644
--- a/core/lib/Drupal/Core/TypedData/Type/IntegerInterface.php
+++ b/core/lib/Drupal/Core/TypedData/Type/IntegerInterface.php
@@ -14,6 +14,8 @@
*
* The plain value of an integer is a regular PHP integer. For setting the value
* any PHP variable that casts to an integer may be passed.
+ *
+ * @ingroup typed_data
*/
interface IntegerInterface extends PrimitiveInterface {
diff --git a/core/lib/Drupal/Core/TypedData/Type/StringInterface.php b/core/lib/Drupal/Core/TypedData/Type/StringInterface.php
index edc29bc0aecb..c72d35922c3c 100644
--- a/core/lib/Drupal/Core/TypedData/Type/StringInterface.php
+++ b/core/lib/Drupal/Core/TypedData/Type/StringInterface.php
@@ -14,6 +14,8 @@
*
* The plain value of a string is a regular PHP string. For setting the value
* any PHP variable that casts to a string may be passed.
+ *
+ * @ingroup typed_data
*/
interface StringInterface extends PrimitiveInterface {
diff --git a/core/lib/Drupal/Core/TypedData/Type/UriInterface.php b/core/lib/Drupal/Core/TypedData/Type/UriInterface.php
index 1034061e8c45..6dbbbd6d57b5 100644
--- a/core/lib/Drupal/Core/TypedData/Type/UriInterface.php
+++ b/core/lib/Drupal/Core/TypedData/Type/UriInterface.php
@@ -13,6 +13,8 @@
* Interface for URIs.
*
* The plain value of a URI is an absolute URI represented as PHP string.
+ *
+ * @ingroup typed_data
*/
interface UriInterface extends PrimitiveInterface {
diff --git a/core/lib/Drupal/Core/TypedData/TypedData.php b/core/lib/Drupal/Core/TypedData/TypedData.php
index fce21d95ec9a..d8fe50d32729 100644
--- a/core/lib/Drupal/Core/TypedData/TypedData.php
+++ b/core/lib/Drupal/Core/TypedData/TypedData.php
@@ -14,6 +14,8 @@
*
* Classes deriving from this base class have to declare $value
* or override getValue() or setValue().
+ *
+ * @ingroup typed_data
*/
abstract class TypedData implements TypedDataInterface, PluginInspectionInterface {
diff --git a/core/lib/Drupal/Core/TypedData/TypedDataInterface.php b/core/lib/Drupal/Core/TypedData/TypedDataInterface.php
index b709a81875b8..c7641b055783 100644
--- a/core/lib/Drupal/Core/TypedData/TypedDataInterface.php
+++ b/core/lib/Drupal/Core/TypedData/TypedDataInterface.php
@@ -13,6 +13,8 @@
* Interface for typed data objects.
*
* @see \Drupal\Core\TypedData\DataDefinitionInterface
+ *
+ * @ingroup typed_data
*/
interface TypedDataInterface {
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 9b0f9ffbe255..19a4c37846e5 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -718,14 +718,60 @@
/**
* @defgroup typed_data Typed Data API
* @{
- * API for defining what type of data is used in fields, configuration, etc.
- *
- * @todo write this
- *
- * Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic.
- *
- * See https://drupal.org/node/1794140
+ * API for describing data based on a set of available data types.
+ *
+ * The Typed Data API was created to provide developers with a consistent
+ * interface for interacting with data, as well as an API for metadata
+ * (information about the data, such as the data type, whether it is
+ * translatable, and who can access it). The Typed Data API is used in several
+ * Drupal sub-systems, such as the Entity Field API and Configuration API.
+ *
+ * See https://drupal.org/node/1794140 for more information about the Typed
+ * Data API.
+ *
+ * @section interfaces Interfaces and classes in the Typed Data API
+ * There are several basic interfaces in the Typed Data API, representing
+ * different types of data:
+ * - \Drupal\Core\TypedData\PrimitiveInterface: Used for primitive data, such
+ * as strings, numeric types, etc. Drupal provides primitive types for
+ * integers, strings, etc. based on this interface, and you should
+ * not ever need to create new primitive types.
+ * - \Drupal\Core\TypedData\TypedDataInterface: Used for single pieces of data,
+ * with some information about its context. Abstract base class
+ * \Drupal\Core\TypedData\TypedData is a useful starting point, and contains
+ * documentation on how to extend it.
+ * - \Drupal\Core\TypedData\ComplexDataInterface: Used for complex data, which
+ * contains named and typed properties; extends TypedDataInterface. Examples
+ * of complex data include content entities and field items. See the
+ * @link entity_api Entity API topic @endlink for more information about
+ * entities; for most complex data, developers should use entities.
+ * - \Drupal\Core\TypedData\ListInterface: Used for a sequential list of other
+ * typed data. Class \Drupal\Core\TypedData\Plugin\DataType\ItemList is a
+ * generic implementation of this interface, and it is used by default for
+ * data declared as a list of some other data type. You can also define a
+ * custom list class, in which case ItemList is a useful base class.
+ *
+ * @section defining Defining data types
+ * To define a new data type:
+ * - Create a class that implements one of the Typed Data interfaces.
+ * Typically, you will want to extend one of the classes listed in the
+ * section above as a starting point.
+ * - Make your class into a DataType plugin. To do that, put it in namespace
+ * \Drupal\yourmodule\Plugin\DataType (where "yourmodule" is your module's
+ * short name), and add annotation of type
+ * \Drupal\Core\TypedData\Annotation\DataType to the documentation header.
+ * See the @link plugin_api Plugin API topic @endlink and the
+ * @link annotation Annotations topic @endlink for more information.
+ *
+ * @section using Using data types
+ * The data types of the Typed Data API can be used in several ways, once they
+ * have been defined:
+ * - In the Field API, data types can be used as the class in the property
+ * definition of the field. See the @link field Field API topic @endlink for
+ * more information.
+ * - In configuration schema files, you can use the unique ID ('id' annotation)
+ * from any DataType plugin class as the 'type' value for an entry. See the
+ * @link config_api Confuration API topic @endlink for more information.
* @}
*/
--
GitLab