diff --git a/core/lib/Drupal/Core/TypedData/Annotation/DataType.php b/core/lib/Drupal/Core/TypedData/Annotation/DataType.php
index 880ec65671fcd74513b70564f1c93ef094a9b2e2..332c3edb6bbc877750643a1f57e5e0a524c7ae14 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 efa5fdfeafb099764aefec05424723f1d1608cf3..5cc15068e95bd4f5efc86423014ee1bcd27409fe 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 39ed9cef6f65a513989a5f4ec3afe71c5987d347..923090ebf8249ddb9fcc1ccb35271f8e62ee3695 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 53d6a567c70dd25c521c6c7a45cd5059963a3029..1b1aecb1a844e918989230f505e3186968b6ae2a 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 334cc9bdb356652480e9cd5189f27b0836eee9e3..a7f2df59d725bc27a098071478af31debee76495 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 67d2cc1c5e016ff0477d64d0978f1240fe915781..c506fe7eeca192d6275a4122d4546fdc90a462cb 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 e8803b311b97e063ef2d118ba8b2f5b9954c836a..bf70d6f56b62099afbef66feded6c672db80571f 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 25b39f8299a951d4ade1b090dfc134acd4662287..54f36484504edeb21325d5bb182702c53cbf5728 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 481eebe6d06b0ebeac2c523d432e38cedb2c90ac..bc699ccb75f9e604e71cda1ef5e8232350f7bd21 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 01ad0d9aed1f5ce53831cb88d98724189b664771..f392ec6f5012b308323044155d16e00e3f3ec2f9 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 6f4b487216aecf0fd8f50676027ddc8b6d1efd95..ec866f8b2874c2d60dcb9780d2f196655a6d6004 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 3bbcd22e143d44bd1ecb5b1495c210389208d74d..e8d17c536919b108bfc62da36065ee2ebb57ad2b 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 9f8e176ebd7520f4e2d66cf080341a6a846bd1bc..70329648e0db882d22e6e07eb0b6f92e8accc577 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 643fcbe33b1867a133b31a85ea67ea941283696f..6cbb91af0450796349a076dd0706209f864f3f4b 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 4554a304fc845d5bfa75da5ecf88d13e6d97679b..6c9368b80124ee958a5c05529922c479b0fa06f1 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 edc29bc0aecb90368d72f0a2af2eb77881b86950..c72d35922c3c3d4dc7e225093c810ad588c32d96 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 1034061e8c4514cc3def7ec5e1d9fb505530aa0c..6dbbbd6d57b53ca94c83106e917f0c3034751072 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 fce21d95ec9a168a7636f95e5aa7795edc99a0ea..d8fe50d327292fc73286ce89cb4f4dbca04890bc 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 b709a81875b8ffcc3e8892e0a5c62365307b5487..c7641b0557831411e2e813b5b645e40c899102e4 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 9b0f9ffbe25575a7294de1bff584592a8f1c5f73..19a4c37846e594108811406fecd0a2e6ae8cc0d6 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.
* @}
*/