Improve documentation of rdf module

Rerolling the patch. This should apply cleanly.

I like the new text. Code comments!

marked #621032: Change api.drupal.org title from 'RDFa API' to 'RDF Mapping API' as duplicate. attached patch from #621032: Change api.drupal.org title from 'RDFa API' to 'RDF Mapping API' should be merged with the running patch #3.

reopening since first alpha is out, it's time to start cleaning up ;)

documentation on hook_rdf_namespaces() is missing. though this hook is invoked in common.inc, it should be documented in rdf.api.php

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -31,7 +31,7 @@ function rdf_help($path, $arg) {
+ * All Drupal core themes are coded to be RDFa compatible.

coded? isn't 'designed' more appropriate here?

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -65,8 +65,10 @@ function rdf_help($path, $arg) {
+ * Sets the bundle name to an empty string. This is used to define default RDF
+ * mappings for an entity. Any bundles of the given entity type that are
+ * created will inherit the default mapping unless a bundle specific mapping
+ * is defined.

should be "Sets the default bundle name...". How about clarifying as follows: Implementation of hook_rdf_mapping() should use this constant for the 'bundle' key when defining a generic set of RDF mapping for an entity type, which will be used as default values for all bundles of this entity type.

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -65,8 +65,10 @@ function rdf_help($path, $arg) {
+ * Sets the bundle name to an empty string. This is used to define default RDF

'Sets the bundle name' should be 'Sets the default bundle name'

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -83,24 +85,31 @@ define('RDF_DEFAULT_BUNDLE', '');
+  // Retrieve the bundle specific mapping from the entity info.

third person

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -83,24 +85,31 @@ define('RDF_DEFAULT_BUNDLE', '');
+  // If there is no mapping defined for this bundle, return the default mapping

returns

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -163,7 +177,8 @@ function _rdf_mapping_load($type, $bundl
+  // If there are any array keys in the default mapping that were not overriden
+  // by the bundle specific mapping, set those to the default value.

I find the order in which the sentence is constructed confusing. What we do here is merge in default mappings for type or fields which don't have a specified mapping.

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -202,7 +217,12 @@ function rdf_mapping_delete($type, $bund
+ * Builds an array of RDFa attributes for a given mapping. This array will be
+ * passed through drupal_attributes() to create the attributes variables that

this is what typically happens, but the way it's worded sounds like it happens automatically. Adding 'typically' to the sentence should solve this confusion.

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -262,9 +282,9 @@ function rdf_rdfa_attributes($mapping, $
  * defined in hook_rdf_mapping(), we do not want to save the default entity
+ * mappings in the database. The default entity mappings can be overriden by

rewording suggestion: "..., default entity mappings are not stored in the database. Only overridden mappings are stored in the database."

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -379,15 +405,17 @@ function rdf_process(&$variables, $hook)
+  // Adds RDFa markup to the node container in teaser view. The about attribute

This is not teaser specific, it is also used in full node mode. (same remarks for all 4 hunks below this one).

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -379,15 +405,17 @@ function rdf_process(&$variables, $hook)
+  // Adds RDFa markup to the title of the node in teaser view. Because the RDFa

this is kind of true but misleading (see above). we don't put it only for teaser here, it's just that in full node the title is not displayed properly. people might wonder what makes this piece of code 'teaser only', I would just not mention teaser here.

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -506,17 +536,17 @@ function rdf_preprocess_username(&$varia
+  // is used to set the URI as the subject of the following predicates. Even if

".. as the default subject of the predicates embedded as RDFa in the children elements..."

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -506,17 +536,17 @@ function rdf_preprocess_username(&$varia
+  // the user profile is not accessible to the current user, we use its URI in ¶

end of line whitespace

+++ modules/rdf/rdf.module	17 Feb 2010 08:13:50 -0000
@@ -506,17 +536,17 @@ function rdf_preprocess_username(&$varia
-  // The remaining attributes are defined by RDFa as lists

It took me some time to remember why we wrote this comment... :) in fact it should be moved to the last line where we use array_merge_recursive(), and clarify the fact that there might be other attributes in $variables['attributes_array'] which we do not want to override, hence the merge.

Powered by Dreditor.

also I just noticed an indentation issue in

 *   @code
 *     array(
 *       'predicates' => array('dc:created'),
 *         'datatype' => 'xsd:dateTime',
 *         'callback' => 'date_iso8601',
 *       ),
 *     );
 *   @endcode

#13: rdf_code-doc_623684_13.patch queued for re-testing.

It all look good, except one last remark:

+++ modules/rdf/rdf.module	18 Feb 2010 18:04:42 -0000
@@ -417,7 +445,8 @@ function rdf_preprocess_node(&$variables
-  // Adds RDFa markup annotating the number of comments a node has.
+  // Adds RDFa markup annotating the number of comments a node has in teaser
+  // view.

This if() block is not teaser specific, we deal with the full node mode a few lines below, so this hunk is not necessary.

we're also ready to go here. #16 is an easy fix, so marking this as novice.

#720610: Move the core RDF namespace definitions in the rdf module has been committed so this section will need to be updated:

+ * Many common namespace prefixes are defined in system_rdf_namespaces().
+ * However, if a module implements hook_rdf_mapping() and uses a prefix that is
+ * not defined in system_rdf_namespaces(), this hook should be used to define

Following #730420: Make html.tpl.php less dependant on rdf namespaces, we can give drupal_get_rdf_namespaces() a less HTML-centric explanation...

/**
 * Return a string containing RDF namespace declarations for use in XML and XHTML output.
 */
function drupal_get_rdf_namespaces() {
  // ...
}

parfait! thanks Lin!

Nice work! Committed to CVS HEAD.

good catch, we should drop the user-defined part.

I've posted a patch to fix #23 in a follow up issue:
#738468: Remove "user-defined" comments from standard install profile

"user-defined" appears in more than one comment on the standard install profile, so it's not purely an RDF documentation issue.

Setting status back to fixed here; please follow up in the new issue.