Commit 5a0893fd authored by webchick's avatar webchick

Issue #2216553 by jhodgdon, fago: Fill in @defgroup/topic docs for Typed Data.

parent 371e7624
......@@ -32,6 +32,8 @@
* @see \Drupal\Core\TypedData\TypedDataManager::create()
* @see hook_data_type_info_alter()
*
* @ingroup typed_data
*
* @Annotation
*/
class DataType extends Plugin {
......
......@@ -11,6 +11,8 @@
* Interface for complex data definitions.
*
* @see \Drupal\Core\TypedData\ComplexDataInterface
*
* @ingroup typed_data
*/
interface ComplexDataDefinitionInterface extends DataDefinitionInterface {
......
......@@ -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 {
......
......@@ -23,6 +23,8 @@
* @see \Drupal\Core\TypedData\ComplexDataDefinitionInterface
* @see \Drupal\Core\TypedData\DataReferenceDefinitionInterface
* @see \Drupal\Core\TypedData\TypedDataInterface
*
* @ingroup typed_data
*/
interface DataDefinitionInterface {
......
......@@ -12,6 +12,8 @@
*
* @see \Drupal\Core\TypedData\DataReferenceDefinition
* @see \Drupal\Core\TypedData\DataReferenceInterface
*
* @ingroup typed_data
*/
interface DataReferenceDefinitionInterface extends DataDefinitionInterface {
......
......@@ -15,6 +15,8 @@
*
* @see \Drupal\Core\TypedData\ListDefinition
* @see \Drupal\Core\TypedData\ListInterface
*
* @ingroup typed_data
*/
interface ListDataDefinitionInterface extends DataDefinitionInterface {
......
......@@ -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 {
......
......@@ -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"),
......
......@@ -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"),
......
......@@ -9,6 +9,8 @@
/**
* Interface for primitive data.
*
* @ingroup typed_data
*/
interface PrimitiveInterface {
......
......@@ -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 {
......
......@@ -11,6 +11,8 @@
/**
* Interface for dates, optionally including a time.
*
* @ingroup typed_data
*/
interface DateTimeInterface {
......
......@@ -9,6 +9,8 @@
/**
* Interface for durations.
*
* @ingroup typed_data
*/
interface DurationInterface {
......
......@@ -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 {
......
......@@ -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 {
......
......@@ -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 {
......
......@@ -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 {
......
......@@ -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 {
......
......@@ -13,6 +13,8 @@
* Interface for typed data objects.
*
* @see \Drupal\Core\TypedData\DataDefinitionInterface
*
* @ingroup typed_data
*/
interface TypedDataInterface {
......
......@@ -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.
* @}
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment