tracker r2399 - in trunk: . src/tracker-indexer

[carlosg svn gnome org]

Author: carlosg
Date: Tue Oct 21 09:04:05 2008
New Revision: 2399
URL: http://svn.gnome.org/viewvc/tracker?rev=2399&view=rev

Log:
2008-10-21  Carlos Garnacho  <carlos imendio com>

        * src/tracker-indexer/tracker-metadata-utils.c:
        * src/tracker-indexer/tracker-metadata.c: Add some methods docs.


Modified:
   trunk/ChangeLog
   trunk/src/tracker-indexer/tracker-metadata-utils.c
   trunk/src/tracker-indexer/tracker-metadata.c

Modified: trunk/src/tracker-indexer/tracker-metadata-utils.c
==============================================================================
--- trunk/src/tracker-indexer/tracker-metadata-utils.c	(original)
+++ trunk/src/tracker-indexer/tracker-metadata-utils.c	Tue Oct 21 09:04:05 2008
@@ -788,6 +788,16 @@
 	return g_string_free (text, FALSE);
 }
 
+/**
+ * tracker_metadata_utils_get_text:
+ * @path: Path to a local file
+ *
+ * Gets the text from a given file, if the file is considered as
+ * containing plain text, it will be extracted, else this function
+ * will resort to the installed text filters for the file MIME type.
+ *
+ * Returns: A newly allocated string containing the file text, or %NULL.
+ **/
 gchar *
 tracker_metadata_utils_get_text (const gchar *path)
 {
@@ -813,6 +823,15 @@
 	return text;
 }
 
+/**
+ * tracker_metadata_utils_get_data:
+ * @path: Path to a local file
+ *
+ * Returns a #TrackerMetadata filled with the most generic
+ * metadata for files, such as file size, MIME type, mtime...
+ *
+ * Returns: A newly created #TrackerMetadata, or %NULL if the file is not found.
+ **/
 TrackerMetadata *
 tracker_metadata_utils_get_data (const gchar *path)
 {

Modified: trunk/src/tracker-indexer/tracker-metadata.c
==============================================================================
--- trunk/src/tracker-indexer/tracker-metadata.c	(original)
+++ trunk/src/tracker-indexer/tracker-metadata.c	Tue Oct 21 09:04:05 2008
@@ -27,6 +27,13 @@
 	GHashTable *table;
 };
 
+/**
+ * tracker_metadata_new:
+ *
+ * Creates a new #TrackerMetadata with no data in it.
+ *
+ * Returns: The newly created #TrackerMetadata
+ **/
 TrackerMetadata *
 tracker_metadata_new (void)
 {
@@ -62,6 +69,12 @@
 	return TRUE;
 }
 
+/**
+ * tracker_metadata_free:
+ * @metadata: A #TrackerMetadata
+ *
+ * Frees the #TrackerMetadata and any contained data.
+ **/
 void
 tracker_metadata_free (TrackerMetadata *metadata)
 {
@@ -73,6 +86,14 @@
 	g_slice_free (TrackerMetadata, metadata);
 }
 
+/**
+ * tracker_metadata_insert:
+ * @metadata: A #TrackerMetadata
+ * @field_name: Field name for the metadata to insert.
+ * @value: Value for the metadata to insert.
+ *
+ * Inserts a new metadata element into @metadata.
+ **/
 void
 tracker_metadata_insert (TrackerMetadata *metadata,
 			 const gchar	 *field_name,
@@ -95,6 +116,15 @@
 			     value);
 }
 
+/**
+ * tracker_metadata_insert_multiple_values:
+ * @metadata: A #TrackerMetadata
+ * @field_name: Field name for the metadata to insert
+ * @list: Value list for the metadata to insert
+ *
+ * Inserts a list of values into @metadata for the given @field_name.
+ * The ontology has to specify that @field_name allows multiple values.
+ **/
 void
 tracker_metadata_insert_multiple_values (TrackerMetadata *metadata,
 					 const gchar	 *field_name,
@@ -112,6 +142,15 @@
 			     list);
 }
 
+/**
+ * tracker_metadata_lookup:
+ * @metadata: A #TrackerMetadata
+ * @field_name: Field name to look up
+ *
+ * Returns the value corresponding to the metadata specified by @field_name.
+ *
+ * Returns: The value. This string is owned by @metadata and must not be modified or freed.
+ **/
 G_CONST_RETURN gchar *
 tracker_metadata_lookup (TrackerMetadata *metadata,
 			 const gchar	 *field_name)
@@ -126,6 +165,16 @@
 	return g_hash_table_lookup (metadata->table, field);
 }
 
+/**
+ * tracker_metadata_lookup_multiple_values:
+ * @metadata: A #TrackerMetadata
+ * @field_name: Field name to look up
+ *
+ * Returns the value list corresponding to the metadata specified by @field_name.
+ *
+ * Returns: A List containing strings. Both the list and the contained strings
+ *          are owned by @metadata and must not be modified or freed.
+ **/
 G_CONST_RETURN GList *
 tracker_metadata_lookup_multiple_values (TrackerMetadata *metadata,
 					 const gchar	 *field_name)
@@ -140,6 +189,14 @@
 	return g_hash_table_lookup (metadata->table, field);
 }
 
+/**
+ * tracker_metadata_foreach:
+ * @metadata: A #TrackerMetadata.
+ * @func: The function to call with each metadata.
+ * @user_data: user data to pass to the function.
+ *
+ * Calls a function for each element in @metadata.
+ **/
 void
 tracker_metadata_foreach (TrackerMetadata	 *metadata,
 			  TrackerMetadataForeach  func,