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. * Gets the entity info array of an entity type.
* *
* @see hook_entity_info()
* @see hook_entity_info_alter()
*
* @param $entity_type * @param $entity_type
* The entity type, e.g. node, for which the info shall be returned, or NULL * The entity type, e.g. node, for which the info shall be returned, or NULL
* to return an array with info about all types. * 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) { function entity_get_info($entity_type = NULL) {
global $language; 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 * @param $entity_type
* The entity type; e.g. 'node' or 'user'. * The entity type; e.g. 'node' or 'user'.
* @param $entity * @param $entity
* The entity from which to extract values. * The entity from which to extract values.
*
* @return * @return
* A numerically indexed array (not a hash table) containing these * A numerically indexed array (not a hash table) containing these
* elements: * elements:
* 0: primary id of the entity * - 0: Primary ID of the entity.
* 1: revision id of the entity, or NULL if $entity_type is not versioned * - 1: Revision ID of the entity, or NULL if $entity_type is not versioned.
* 2: bundle name of the entity * - 2: Bundle name of the entity.
*/ */
function entity_extract_ids($entity_type, $entity) { function entity_extract_ids($entity_type, $entity) {
$info = entity_get_info($entity_type); $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(). * This function can be seen as reciprocal to entity_extract_ids().
* *
@ -168,9 +169,9 @@ function entity_extract_ids($entity_type, $entity) {
* @param $ids * @param $ids
* A numerically indexed array, as returned by entity_extract_ids(), * A numerically indexed array, as returned by entity_extract_ids(),
* containing these elements: * containing these elements:
* 0: primary id of the entity * - 0: Primary ID of the entity.
* 1: revision id of the entity, or NULL if $entity_type is not versioned * - 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 * - 2: Bundle name of the entity, or NULL if $entity_type has no bundles.
* *
* @return * @return
* An entity object, initialized with the IDs provided. * 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 * DrupalDefaultEntityController class. See node_entity_info() and the
* NodeController in node.module as an example. * NodeController in node.module as an example.
* *
* @see hook_entity_info()
* @see DrupalEntityControllerInterface
* @see DrupalDefaultEntityController
* @see EntityFieldQuery
*
* @param $entity_type * @param $entity_type
* The entity type to load, e.g. node or user. * The entity type to load, e.g. node or user.
* @param $ids * @param $ids
@ -226,6 +222,11 @@ function entity_create_stub_entity($entity_type, $ids) {
* An array of entity objects indexed by their ids. * An array of entity objects indexed by their ids.
* *
* @todo Remove $conditions in Drupal 8. * @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) { function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset = FALSE) {
if ($reset) { if ($reset) {
@ -245,7 +246,7 @@ function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset =
* @param $entity_type * @param $entity_type
* The entity type to load, e.g. node or user. * The entity type to load, e.g. node or user.
* @param $id * @param $id
* The id of the entity to load. * The ID of the entity to load.
* *
* @return * @return
* The unchanged entity, or FALSE if the entity cannot be loaded. * 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 * field_attach_prepare_view() to allow entity level hooks to act on content
* loaded by field API. * loaded by field API.
* *
* @see hook_entity_prepare_view()
*
* @param $entity_type * @param $entity_type
* The type of entity, i.e. 'node', 'user'. * The type of entity, i.e. 'node', 'user'.
* @param $entities * @param $entities
* The entity objects which are being prepared for view, keyed by object ID. * 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) { function entity_prepare_view($entity_type, $entities) {
// To ensure hooks are only run once per entity, check for an // 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) { function entity_form_field_validate($entity_type, $form, &$form_state) {
// All field attach API functions act on an entity object, but during form // 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 * 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 * 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 { } 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. * other storage engines might not do this.
*/ */
class EntityFieldQuery { class EntityFieldQuery {
/** /**
* Indicates that both deleted and non-deleted fields should be returned. * Indicates that both deleted and non-deleted fields should be returned.
* *
@ -590,7 +591,8 @@ class EntityFieldQuery {
* Enables sortable tables for this query. * Enables sortable tables for this query.
* *
* @param $headers * @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 * @return EntityFieldQuery
* The called object. * The called object.

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

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

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

@ -1,8 +1,14 @@
<?php <?php
/** /**
* Test invocation of hooks when inserting, loading, updating or deleting an * @file
* entity. Tested hooks are: * CRUD hook tests for the Entity CRUD API.
*/
/**
* Tests invocation of hooks when performing an action.
*
* Tested hooks are:
* - hook_entity_insert() * - hook_entity_insert()
* - hook_entity_load() * - hook_entity_load()
* - hook_entity_update() * - 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() { public function testCommentHooks() {
$node = (object) array( $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() { public function testFileHooks() {
$url = 'public://entity_crud_hook_test.file'; $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() { public function testNodeHooks() {
$node = (object) array( $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() { public function testTaxonomyTermHooks() {
$vocabulary = (object) array( $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() { public function testTaxonomyVocabularyHooks() {
$vocabulary = (object) array( $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() { public function testUserHooks() {
$edit = array( $edit = array(