Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Issue #1315340 by aspilicious: Clean up API docs for entity module.

8.0.x
catch 2012-01-19 21:43:21 +09:00
parent 1c147ddb06
commit d2b8164d57
4 changed files with 44 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
core/modules/entity/entity.module
View File

@ -35,12 +35,12 @@ function entity_modules_disabled() {
/**
* Gets the entity info array of an entity type.
*
* @see hook_entity_info()
* @see hook_entity_info_alter()
*
* @param $entity_type
* The entity type, e.g. node, for which the info shall be returned, or NULL
* to return an array with info about all types.
*
* @see hook_entity_info()
* @see hook_entity_info_alter()
*/
function entity_get_info($entity_type = NULL) {
global $language;
@ -122,18 +122,19 @@ function entity_info_cache_clear() {
}
/**
* Helper function to extract id, vid, and bundle name from an entity.
* Extracts ID, revision ID, and bundle name from an entity.
*
* @param $entity_type
* The entity type; e.g. 'node' or 'user'.
* @param $entity
* The entity from which to extract values.
*
* @return
* A numerically indexed array (not a hash table) containing these
* elements:
* 0: primary id of the entity
* 1: revision id of the entity, or NULL if $entity_type is not versioned
* 2: bundle name of the entity
* - 0: Primary ID of the entity.
* - 1: Revision ID of the entity, or NULL if $entity_type is not versioned.
* - 2: Bundle name of the entity.
*/
function entity_extract_ids($entity_type, $entity) {
$info = entity_get_info($entity_type);
@ -159,7 +160,7 @@ function entity_extract_ids($entity_type, $entity) {
}
/**
* Helper function to assemble an object structure with initial ids.
* Assembles an object structure with initial IDs.
*
* This function can be seen as reciprocal to entity_extract_ids().
*
@ -168,9 +169,9 @@ function entity_extract_ids($entity_type, $entity) {
* @param $ids
* A numerically indexed array, as returned by entity_extract_ids(),
* containing these elements:
* 0: primary id of the entity
* 1: revision id of the entity, or NULL if $entity_type is not versioned
* 2: bundle name of the entity, or NULL if $entity_type has no bundles
* - 0: Primary ID of the entity.
* - 1: Revision ID of the entity, or NULL if $entity_type is not versioned.
* - 2: Bundle name of the entity, or NULL if $entity_type has no bundles.
*
* @return
* An entity object, initialized with the IDs provided.
@ -205,11 +206,6 @@ function entity_create_stub_entity($entity_type, $ids) {
* DrupalDefaultEntityController class. See node_entity_info() and the
* NodeController in node.module as an example.
*
* @see hook_entity_info()
* @see DrupalEntityControllerInterface
* @see DrupalDefaultEntityController
* @see EntityFieldQuery
*
* @param $entity_type
* The entity type to load, e.g. node or user.
* @param $ids
@ -226,6 +222,11 @@ function entity_create_stub_entity($entity_type, $ids) {
* An array of entity objects indexed by their ids.
*
* @todo Remove $conditions in Drupal 8.
*
* @see hook_entity_info()
* @see DrupalEntityControllerInterface
* @see DrupalDefaultEntityController
* @see EntityFieldQuery
*/
function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset = FALSE) {
if ($reset) {
@ -245,7 +246,7 @@ function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset =
* @param $entity_type
* The entity type to load, e.g. node or user.
* @param $id
* The id of the entity to load.
* The ID of the entity to load.
*
* @return
* The unchanged entity, or FALSE if the entity cannot be loaded.
@ -313,12 +314,12 @@ function entity_get_controller($entity_type) {
* field_attach_prepare_view() to allow entity level hooks to act on content
* loaded by field API.
*
* @see hook_entity_prepare_view()
*
* @param $entity_type
* The type of entity, i.e. 'node', 'user'.
* @param $entities
* The entity objects which are being prepared for view, keyed by object ID.
*
* @see hook_entity_prepare_view()
*/
function entity_prepare_view($entity_type, $entities) {
// To ensure hooks are only run once per entity, check for an
@ -414,7 +415,7 @@ function entity_label($entity_type, $entity) {
}
/**
* Helper function for attaching field API validation to entity forms.
* Attaches field API validation to entity forms.
*/
function entity_form_field_validate($entity_type, $form, &$form_state) {
// All field attach API functions act on an entity object, but during form
@ -427,7 +428,7 @@ function entity_form_field_validate($entity_type, $form, &$form_state) {
}
/**
* Helper function for copying submitted values to entity properties for simple entity forms.
* Copies submitted values to entity properties for simple entity forms.
*
* During the submission handling of an entity form's "Save", "Preview", and
* possibly other buttons, the form state's entity needs to be updated with the
@ -473,6 +474,6 @@ function entity_form_submit_build_entity($entity_type, $entity, $form, &$form_st
}
/**
* Exception thrown when a malformed entity is passed.
* Defines an exception thrown when a malformed entity is passed.
*/
class EntityMalformedException extends Exception { }

4
core/modules/entity/entity.query.inc
View File

@ -43,6 +43,7 @@ class EntityFieldQueryException extends Exception {}
* other storage engines might not do this.
*/
class EntityFieldQuery {
/**
* Indicates that both deleted and non-deleted fields should be returned.
*
@ -590,7 +591,8 @@ class EntityFieldQuery {
* Enables sortable tables for this query.
*
* @param $headers
* An EFQ Header array based on which the order clause is added to the query.
* An EFQ Header array based on which the order clause is added to the
* query.
*
* @return EntityFieldQuery
* The called object.

27
core/modules/entity/tests/entity_crud_hook_test.module
View File

@ -1,8 +1,9 @@
<?php
//
// Presave hooks
//
/**
* @file
* Test module for the Entity CRUD API.
*/
/**
* Implements hook_entity_presave().
@ -53,10 +54,6 @@ function entity_crud_hook_test_user_presave() {
$_SESSION['entity_crud_hook_test'][] = (__FUNCTION__ . ' called');
}
//
// Insert hooks
//
/**
* Implements hook_entity_insert().
*/
@ -106,10 +103,6 @@ function entity_crud_hook_test_user_insert() {
$_SESSION['entity_crud_hook_test'][] = (__FUNCTION__ . ' called');
}
//
// Load hooks
//
/**
* Implements hook_entity_load().
*/
@ -159,10 +152,6 @@ function entity_crud_hook_test_user_load() {
$_SESSION['entity_crud_hook_test'][] = (__FUNCTION__ . ' called');
}
//
// Update hooks
//
/**
* Implements hook_entity_update().
*/
@ -212,10 +201,6 @@ function entity_crud_hook_test_user_update() {
$_SESSION['entity_crud_hook_test'][] = (__FUNCTION__ . ' called');
}
//
// Predelete hooks
//
/**
* Implements hook_entity_predelete().
*/
@ -265,10 +250,6 @@ function entity_crud_hook_test_user_predelete() {
$_SESSION['entity_crud_hook_test'][] = (__FUNCTION__ . ' called');
}
//
// Delete hooks
//
/**
* Implements hook_entity_delete().
*/

22
core/modules/entity/tests/entity_crud_hook_test.test
View File

@ -1,8 +1,14 @@
<?php
/**
* Test invocation of hooks when inserting, loading, updating or deleting an
* entity. Tested hooks are:
* @file
* CRUD hook tests for the Entity CRUD API.
*/
/**
* Tests invocation of hooks when performing an action.
*
* Tested hooks are:
* - hook_entity_insert()
* - hook_entity_load()
* - hook_entity_update()
@ -53,7 +59,7 @@ class EntityCrudHookTestCase extends DrupalWebTestCase {
}
/**
* Test hook invocations for CRUD operations on comments.
* Tests hook invocations for CRUD operations on comments.
*/
public function testCommentHooks() {
$node = (object) array(
@ -124,7 +130,7 @@ class EntityCrudHookTestCase extends DrupalWebTestCase {
}
/**
* Test hook invocations for CRUD operations on files.
* Tests hook invocations for CRUD operations on files.
*/
public function testFileHooks() {
$url = 'public://entity_crud_hook_test.file';
@ -180,7 +186,7 @@ class EntityCrudHookTestCase extends DrupalWebTestCase {
}
/**
* Test hook invocations for CRUD operations on nodes.
* Tests hook invocations for CRUD operations on nodes.
*/
public function testNodeHooks() {
$node = (object) array(
@ -236,7 +242,7 @@ class EntityCrudHookTestCase extends DrupalWebTestCase {
}
/**
* Test hook invocations for CRUD operations on taxonomy terms.
* Tests hook invocations for CRUD operations on taxonomy terms.
*/
public function testTaxonomyTermHooks() {
$vocabulary = (object) array(
@ -294,7 +300,7 @@ class EntityCrudHookTestCase extends DrupalWebTestCase {
}
/**
* Test hook invocations for CRUD operations on taxonomy vocabularies.
* Tests hook invocations for CRUD operations on taxonomy vocabularies.
*/
public function testTaxonomyVocabularyHooks() {
$vocabulary = (object) array(
@ -344,7 +350,7 @@ class EntityCrudHookTestCase extends DrupalWebTestCase {
}
/**
* Test hook invocations for CRUD operations on users.
* Tests hook invocations for CRUD operations on users.
*/
public function testUserHooks() {
$edit = array(