From 07b97cf1271c7725e4e03681af5602fb63c63d54 Mon Sep 17 00:00:00 2001 From: kotnik Date: Mon, 30 Jan 2012 09:47:37 +0100 Subject: [PATCH] Issue #1418980 by kotnik: Clean up API docs for rdf. --- core/modules/rdf/rdf.module | 96 ++++++++++++++++++++++++------------------ 1 files changed, 55 insertions(+), 41 deletions(-) diff --git a/core/modules/rdf/rdf.module b/core/modules/rdf/rdf.module index 1e1485e..e79110e 100644 --- a/core/modules/rdf/rdf.module +++ b/core/modules/rdf/rdf.module @@ -75,6 +75,9 @@ const RDF_DEFAULT_BUNDLE = ''; /** * Implements hook_rdf_namespaces(). + * + * @return array + * Supported RDF namespaces. */ function rdf_rdf_namespaces() { return array( @@ -91,8 +94,13 @@ function rdf_rdf_namespaces() { } /** - * Returns an array of RDF namespaces defined in modules that implement - * hook_rdf_namespaces(). + * Retrieves RDF namespaces. + * + * Invokes hook_rdf_namespaces() and collects RDF namespaces from modules that + * implement it. + * + * @return array + * Array of RDF namespaces. */ function rdf_get_namespaces() { $rdf_namespaces = module_invoke_all('rdf_namespaces'); @@ -121,12 +129,12 @@ function rdf_get_namespaces() { /** * Returns the mapping for attributes of a given entity type/bundle pair. * - * @param $type + * @param string $type * An entity type. - * @param $bundle + * @param string $bundle * (optional) A bundle name. * - * @return + * @return array * The mapping corresponding to the requested entity type/bundle pair or an * empty array. */ @@ -148,12 +156,12 @@ function rdf_mapping_load($type, $bundle = RDF_DEFAULT_BUNDLE) { */ /** - * Helper function to get the default RDF mapping for a given entity type. + * Gets the default RDF mapping for a given entity type. * - * @param $type + * @param string $type * An entity type, e.g. 'node' or 'comment'. * - * @return + * @return array * The RDF mapping or an empty array if no mapping is defined for this entity * type. */ @@ -179,14 +187,14 @@ function _rdf_get_default_mapping($type) { } /** - * Helper function to retrieve an RDF mapping from the database. + * Retrieves an RDF mapping from the database. * - * @param $type + * @param string $type * The entity type the mapping refers to. - * @param $bundle + * @param string $bundle * The bundle the mapping refers to. * - * @return + * @return array * An RDF mapping structure or an empty array if no record was found. */ function _rdf_mapping_load($type, $bundle) { @@ -216,11 +224,11 @@ function _rdf_mapping_load($type, $bundle) { * type/bundle pair. If available, adds default values for non-existent mapping * keys. * - * @param $mapping - * The RDF mapping to save, as an array. + * @param array $mapping + * The RDF mapping to save. * - * @return - * Status flag indicating the outcome of the operation. + * @return MergeQuery + * MergeQuery object that indicates the outcome of the operation. */ function rdf_mapping_save($mapping) { // In the case where a field has a mapping defined in the default entity @@ -246,13 +254,13 @@ function rdf_mapping_save($mapping) { /** * Deletes the mapping for the given bundle from the database. * - * @param $type + * @param string $type * The entity type the mapping refers to. - * @param $bundle + * @param string $bundle * The bundle the mapping refers to. * - * @return - * Return boolean TRUE if mapping deleted, FALSE if not. + * @return bool + * Return TRUE if mapping is deleted, FALSE if not. */ function rdf_mapping_delete($type, $bundle) { $num_rows = db_delete('rdf_mapping') @@ -264,14 +272,14 @@ function rdf_mapping_delete($type, $bundle) { } /** - * Builds an array of RDFa attributes for a given mapping. This array will - * typically be passed through drupal_attributes() to create the attributes - * variables that are available to template files. These include $attributes, - * $title_attributes, $content_attributes and the field-specific - * $item_attributes variables. For more information, see - * theme_rdf_template_variable_wrapper(). + * Builds an array of RDFa attributes for a given mapping. + * + * Array of RDFa attributes will typically be passed through + * drupal_attributes() to create the attributes variables that are available to + * template files. These include $attributes, $title_attributes, + * $content_attributes and the field-specific $item_attributes variables. * - * @param $mapping + * @param array $mapping * An array containing a mandatory 'predicates' key and optional 'datatype', * 'callback' and 'type' keys. For example: * @code @@ -282,12 +290,15 @@ function rdf_mapping_delete($type, $bundle) { * ), * ); * @endcode - * @param $data - * A value that needs to be converted by the provided callback function. + * @param string $data + * (optional) A value that needs to be converted by the provided callback + * function. * - * @return - * An array containing RDFa attributes suitable for drupal_attributes(). - */ + * @return array + * RDFa attributes suitable for drupal_attributes(). + * + * @see theme_rdf_template_variable_wrapper() +*/ function rdf_rdfa_attributes($mapping, $data = NULL) { // The type of mapping defaults to 'property'. $type = isset($mapping['type']) ? $mapping['type'] : 'property'; @@ -359,11 +370,12 @@ function rdf_modules_uninstalled($modules) { * * Adds the proper RDF mapping to each entity type/bundle pair. * + * This hook should not be used by modules to alter the bundle mappings. The UI + * should always be authoritative. UI mappings are stored in the database and + * if hook_entity_info_alter was used to override module defined mappings, it + * would override the user defined mapping as well. + * * @todo May need to move the comment below to another place. - * This hook should not be used by modules to alter the bundle mappings. - * The UI should always be authoritative. UI mappings are stored in the - * database and if hook_entity_info_alter was used to override module defined - * mappings, it would override the user defined mapping as well. */ function rdf_entity_info_alter(&$entity_info) { // Loop through each entity type and its bundles. @@ -425,6 +437,8 @@ function rdf_theme() { } /** + * Implements MODULE_process(). + * * Template process function for adding extra tags to hold RDFa attributes. * * Since template files already have built-in support for $attributes, @@ -434,9 +448,9 @@ function rdf_theme() { * with those here. */ function rdf_process(&$variables, $hook) { - // Handles attributes needed for content not covered by title, content, - // and field items. It does this by adjusting the variable sent to the - // template so that the template doesn't have to worry about it. See + // Handles attributes needed for content not covered by title, content, and + // field items. It does this by adjusting the variable sent to the template + // so that the template doesn't have to worry about it. See // theme_rdf_template_variable_wrapper(). if (!empty($variables['rdf_template_variable_attributes_array'])) { foreach ($variables['rdf_template_variable_attributes_array'] as $variable_name => $attributes) { @@ -808,7 +822,7 @@ function rdf_preprocess_image(&$variables) { * drupal_attributes($rdf_template_variable_attributes_array[$variable_name]) * @endcode * - * @param $variables + * @param array $variables * An associative array containing: * - content: A string of content to be wrapped with attributes. * - attributes: An array of attributes to be placed on the wrapping element. @@ -858,7 +872,7 @@ function theme_rdf_template_variable_wrapper($variables) { * We can express it in RDFa via empty tags. These aren't visible and * give machines extra information about the content and its structure. * - * @param $variables + * @param array $variables * An associative array containing: * - metadata: An array of attribute arrays. Each item in the array * corresponds to its own set of attributes, and therefore, needs its own -- 1.7.9