Document kind, name, plural for entity config

packages/core-data/README.md

@@ -48,21 +48,23 @@ As of right now, the default entities defined by this package map to the [REST A
 
 What follows is a description of some of the properties of `rootEntitiesConfig`.
 
-## baseURL
+### Connecting the entity with the data source
+
+#### baseURL
 
 -   Type: string.
 -   Example: `'/wp/v2/users'`.
 
 This property maps the entity to a given endpoint, taking its relative URL as value.
 
-## baseURLParams
+#### baseURLParams
 
 -   Type: `object`.
 -   Example: `{ context: 'edit' }`.
 
 Additional parameters to the request, added as a query string. Each property will be converted into a field/value pair. For example, given the `baseURL: '/wp/v2/users'` and the `baseURLParams: { context: 'edit' }` the URL would be `/wp/v2/users?context=edit`.
 
-## key
+#### key
 
 -   Type: `string`.
 -   Example: `'slug'`.
@@ -99,6 +101,61 @@ There are also cases in which a response represents a collection shaped as an ob
 }
 ```
 
+### Interacting with entity records
+
+Entity records are unique. For entities that are collections, it's assumed that each record has an `id` property which serves as an identifier to manage it. If the entity defines a `key`, that property would be used as its identifier instead of the assumed `id`.
+
+#### name
+
+- Type: `string`.
+- Example: `user`.
+
+The name of the entity. To be used in the utilities that interact with it (selectors, actions, hooks).
+
+#### kind
+
+- Type: `string`.
+- Example: `root`.
+
+Entities can be grouped by `kind`. To be used in the utilities that interact with them (selectors, actions, hooks).
+
+The package provides general methods to interact with the entities (`getEntityRecords`, `getEntityRecord`, etc.) by leveraging the `kind` and `name` properties:
+
+```js
+// Get the record collection for the user entity.
+wp.data.select( 'core' ).getEntityRecords( 'root' 'user' );
+
+// Get a single record for the user entity.
+wp.data.select( 'core' ).getEntityRecord( 'root', 'user', recordId );
+```
+
+#### plural
+
+- Type: `string`.
+- Example: `postStatuses`.
+
+In addition to the general utilites (`getEntityRecords`, `getEntityRecord`, etc.), the package dynamically creates nicer-looking methods to interact with the entity records of the `root` kind, both the collection and single records. Compare the general and nicer-looking methods as it follows:
+
+```js
+// Collection
+wp.data.select( 'core' ).getEntityRecords( 'root' 'user' );
+wp.data.select( 'core' ).getUsers();
+
+// Single record
+wp.data.select( 'core' ).getEntityRecord( 'root', 'user', recordId );
+wp.data.select( 'core' ).getUser( recordId );
+```
+
+Sometimes, the pluralized form of an entity is not regular (it is not formed by adding a `-s` suffix). The `plural` property of the entity config allows to declare an alternative pluralized form for the dynamic methods created for the entity. For example, given the `status` entity that declares the `postStatuses` plural, there are the following methods created for it:
+
+```js
+// Collection
+wp.data.select( 'core' ).getPostStatuses();
+
+// Single record
+wp.data.select( 'core' ).getStatus( recordId );
+```
+
 ## Actions
 
 The following set of dispatching action creators are available on the object returned by `wp.data.dispatch( 'core' )`: