[grilo] doc: Clarify grl_data_length() function

[Juan A. Suarez Romero <jasuarez src gnome org>]

commit bbd37c142eaeb528902fd0770184330f0ab70147
Author: Juan A. Suarez Romero <jasuarez igalia com>
Date:   Wed Mar 30 09:50:08 2011 +0200

    doc: Clarify grl_data_length() function
    
    Rewrite function documentation so it is clearer how this function works.
    
    Signed-off-by: Juan A. Suarez Romero <jasuarez igalia com>

 src/data/grl-data.c |   11 ++++++++++-
 1 files changed, 10 insertions(+), 1 deletions(-)
---
diff --git a/src/data/grl-data.c b/src/data/grl-data.c
index b5a134e..64bc7ad 100644
--- a/src/data/grl-data.c
+++ b/src/data/grl-data.c
@@ -764,7 +764,16 @@ grl_data_add_binary (GrlData *data,
  * @data: a data
  * @key: a metadata key
  *
- * Returns how many values @key has in @data.
+ * Returns how many values @key or related keys have in @data: if @key has no
+ * value, but a related key has, then it is counted as positive.
+ *
+ * As example, let's think in three related keys, K1, K2 and K3, and then thinks
+ * we have added several values for those keys, as:
+ *
+ *   (V10, V20, V30),, (V11, NULL, V31), (V12, NULL, V32)
+ *
+ * Therefore, when invoking grl_data_length (data, K2) it will return 3:
+ * considering K2 and the related keys (K1 and K3), there are 3 values.
  *
  * Returns: number of values
  *