[gupnp-dlna/wip/new-api: 43/46] Document new API, fix annotations.



commit cd60c320253e0cb1b374ba1512305874ac656c41
Author: Krzesimir Nowak <krnowak openismus com>
Date:   Fri Jan 4 16:00:11 2013 +0100

    Document new API, fix annotations.
    
    Most of the GUPnPDLNA*Information API is skipped by GObject
    Introspection, though. I have to learn whether it is possible to have
    API returning simple structs by value to be bindable.

 .../gupnp-dlna-metadata-docs.sgml                  |    6 --
 doc/gupnp-dlna/Makefile.am                         |   16 +++-
 doc/gupnp-dlna/gupnp-dlna-docs.sgml                |    9 ++
 libgupnp-dlna/gupnp-dlna-audio-information.c       |   31 ++++----
 libgupnp-dlna/gupnp-dlna-container-information.c   |   19 ++---
 libgupnp-dlna/gupnp-dlna-g-values.c                |   74 ++++++++++++++++++-
 libgupnp-dlna/gupnp-dlna-image-information.c       |   15 ++--
 libgupnp-dlna/gupnp-dlna-profile.c                 |   81 ++++++++++++++------
 libgupnp-dlna/gupnp-dlna-profile.h                 |    8 +-
 libgupnp-dlna/gupnp-dlna-restriction.c             |   46 +++++++++++
 libgupnp-dlna/gupnp-dlna-value-list.c              |   38 +++++++++
 libgupnp-dlna/gupnp-dlna-value.c                   |    4 +-
 libgupnp-dlna/gupnp-dlna-video-information.c       |   29 ++++----
 13 files changed, 287 insertions(+), 89 deletions(-)
---
diff --git a/doc/gupnp-dlna-metadata/gupnp-dlna-metadata-docs.sgml b/doc/gupnp-dlna-metadata/gupnp-dlna-metadata-docs.sgml
index e4daf35..f8c23c6 100644
--- a/doc/gupnp-dlna-metadata/gupnp-dlna-metadata-docs.sgml
+++ b/doc/gupnp-dlna-metadata/gupnp-dlna-metadata-docs.sgml
@@ -46,12 +46,6 @@
       the profile.
     </para>
 
-    <xi:include href="xml/gupnp-dlna-information.xml"/>
-    <xi:include href="xml/gupnp-dlna-values.xml"/>
-    <xi:include href="xml/gupnp-dlna-audio-information.xml"/>
-    <xi:include href="xml/gupnp-dlna-container-information.xml"/>
-    <xi:include href="xml/gupnp-dlna-image-information.xml"/>
-    <xi:include href="xml/gupnp-dlna-video-information.xml"/>
     <xi:include href="xml/gupnp-dlna-metadata-extractor.xml"/>
     <xi:include href="xml/api-index-full.xml"/>
 
diff --git a/doc/gupnp-dlna/Makefile.am b/doc/gupnp-dlna/Makefile.am
index d452e8f..6f94ab7 100644
--- a/doc/gupnp-dlna/Makefile.am
+++ b/doc/gupnp-dlna/Makefile.am
@@ -32,7 +32,7 @@ SCAN_OPTIONS=--deprecated-guards="GUPNP_DISABLE_DEPRECATED"
 MKDB_OPTIONS = \
 	--sgml-mode \
 	--output-format=xml \
-	--ignore-files="metadata metadata-backends profile-backends"
+	--ignore-files="metadata metadata-backends"
 
 # Extra options to supply to gtkdoc-mktmpl
 # e.g. MKTMPL_OPTIONS=--only-section-tmpl
@@ -57,12 +57,20 @@ CFILE_GLOB=$(top_srcdir)/libgupnp-dlna/*.c
 IGNORE_HFILES = \
 	metadata \
 	metadata-backends \
-	profile-backends \
 	gupnp-dlna-field-value.h \
 	gupnp-dlna-metadata-backend.h \
-	gupnp-dlna-profile-backend.h \
 	gupnp-dlna-profile-guesser-impl.h \
-	gupnp-dlna-profile-loader.h
+	gupnp-dlna-profile-loader.h \
+	gupnp-dlna-g-values-private.h \
+	gupnp-dlna-info-set.h \
+	gupnp-dlna-info-value.h \
+	gupnp-dlna-profile-private.h \
+	gupnp-dlna-restriction-private.h \
+	gupnp-dlna-utils.h \
+	gupnp-dlna-value.h \
+	gupnp-dlna-value-list-private.h \
+	gupnp-dlna-value-type.h \
+	gupnp-dlna-value-union.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
diff --git a/doc/gupnp-dlna/gupnp-dlna-docs.sgml b/doc/gupnp-dlna/gupnp-dlna-docs.sgml
index a23c534..1afa00b 100644
--- a/doc/gupnp-dlna/gupnp-dlna-docs.sgml
+++ b/doc/gupnp-dlna/gupnp-dlna-docs.sgml
@@ -59,6 +59,15 @@
 
     <xi:include href="xml/gupnp-dlna-profile-guesser.xml"/>
     <xi:include href="xml/gupnp-dlna-profile.xml"/>
+    <xi:include href="xml/gupnp-dlna-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-values.xml"/>
+    <xi:include href="xml/gupnp-dlna-audio-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-container-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-image-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-video-information.xml"/>
+    <xi:include href="xml/gupnp-dlna-restriction.xml"/>
+    <xi:include href="xml/gupnp-dlna-value-list.xml"/>
+    <xi:include href="xml/gupnp-dlna-g-values.xml"/>
     <xi:include href="xml/api-index-full.xml"/>
 
   </chapter>
diff --git a/libgupnp-dlna/gupnp-dlna-audio-information.c b/libgupnp-dlna/gupnp-dlna-audio-information.c
index 3fd7ca6..ed1f121 100644
--- a/libgupnp-dlna/gupnp-dlna-audio-information.c
+++ b/libgupnp-dlna/gupnp-dlna-audio-information.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2012 Intel Corporation.
+ * Copyright (C) 2012, 2013 Intel Corporation.
  *
  * Authors: Krzesimir Nowak <krnowak openismus com>
  *
@@ -23,6 +23,8 @@
  * SECTION:gupnp-dlna-audio-information
  * @short_description: Base class representing audio metadata needed
  * for DLNA profiles matching.
+ * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
+ * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  *
  * #GUPnPDLNAAudioInformation holds all audio metadatas important for
  * matching profiles. Note that it does not mean all data should be
@@ -41,9 +43,6 @@
  * Note that gupnp_dlna_audio_information_get_mime() should always
  * return a set value. Otherwise it is highly probably that the file
  * will not match against any DLNA profile.
- *
- * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
- * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  */
 
 #include "gupnp-dlna-audio-information.h"
@@ -89,7 +88,7 @@ gupnp_dlna_audio_information_init (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_bitrate:
+ * gupnp_dlna_audio_information_get_bitrate: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A bitrate.
@@ -114,7 +113,7 @@ gupnp_dlna_audio_information_get_bitrate (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_channels:
+ * gupnp_dlna_audio_information_get_channels: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A number of channels.
@@ -139,7 +138,7 @@ gupnp_dlna_audio_information_get_channels (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_depth:
+ * gupnp_dlna_audio_information_get_depth: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A depth.
@@ -164,7 +163,7 @@ gupnp_dlna_audio_information_get_depth (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_layer:
+ * gupnp_dlna_audio_information_get_layer: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A layer.
@@ -189,7 +188,7 @@ gupnp_dlna_audio_information_get_layer (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_level:
+ * gupnp_dlna_audio_information_get_level: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A level.
@@ -214,7 +213,7 @@ gupnp_dlna_audio_information_get_level (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_mpeg_audio_version:
+ * gupnp_dlna_audio_information_get_mpeg_audio_version: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: An MPEG audio version.
@@ -240,7 +239,7 @@ gupnp_dlna_audio_information_get_mpeg_audio_version
 }
 
 /**
- * gupnp_dlna_audio_information_get_mpeg_version:
+ * gupnp_dlna_audio_information_get_mpeg_version: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: An MPEG version.
@@ -265,7 +264,7 @@ gupnp_dlna_audio_information_get_mpeg_version (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_profile:
+ * gupnp_dlna_audio_information_get_profile: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A profile.
@@ -290,7 +289,7 @@ gupnp_dlna_audio_information_get_profile (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_rate:
+ * gupnp_dlna_audio_information_get_rate: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A sample rate.
@@ -315,7 +314,7 @@ gupnp_dlna_audio_information_get_rate (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_stream_format:
+ * gupnp_dlna_audio_information_get_stream_format: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A stream format.
@@ -340,7 +339,7 @@ gupnp_dlna_audio_information_get_stream_format (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_wma_version:
+ * gupnp_dlna_audio_information_get_wma_version: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A WMA version.
@@ -365,7 +364,7 @@ gupnp_dlna_audio_information_get_wma_version (GUPnPDLNAAudioInformation *info)
 }
 
 /**
- * gupnp_dlna_audio_information_get_mime:
+ * gupnp_dlna_audio_information_get_mime: (skip)
  * @info: A #GUPnPDLNAAudioInformation object.
  *
  * Returns: A MIME type.
diff --git a/libgupnp-dlna/gupnp-dlna-container-information.c b/libgupnp-dlna/gupnp-dlna-container-information.c
index b96c2fb..f2b052b 100644
--- a/libgupnp-dlna/gupnp-dlna-container-information.c
+++ b/libgupnp-dlna/gupnp-dlna-container-information.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2012 Intel Corporation.
+ * Copyright (C) 2012, 2013 Intel Corporation.
  *
  * Authors: Krzesimir Nowak <krnowak openismus com>
  *
@@ -23,6 +23,8 @@
  * SECTION:gupnp-dlna-container-information
  * @short_description: Base class representing container metadata
  * needed for DLNA profiles matching.
+ * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
+ * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  *
  * #GUPnPDLNAContainerInformation holds all container metadatas
  * important for matching profiles. Note that it does not mean all
@@ -42,9 +44,6 @@
  * Note that gupnp_dlna_container_information_get_mime() should always
  * return a set value. Otherwise it is highly probably that the file
  * will not match against any DLNA profile.
- *
- * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
- * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  */
 
 #include "gupnp-dlna-container-information.h"
@@ -85,7 +84,7 @@ gupnp_dlna_container_information_init (GUPnPDLNAContainerInformation *info)
 }
 
 /**
- * gupnp_dlna_container_information_get_mpeg_version:
+ * gupnp_dlna_container_information_get_mpeg_version: (skip)
  * @info: A #GUPnPDLNAContainerInformation object.
  *
  * Returns: An MPEG version.
@@ -111,7 +110,7 @@ gupnp_dlna_container_information_get_mpeg_version
 }
 
 /**
- * gupnp_dlna_container_information_get_packet_size:
+ * gupnp_dlna_container_information_get_packet_size: (skip)
  * @info: A #GUPnPDLNAContainerInformation object.
  *
  * Returns: A packet size.
@@ -137,7 +136,7 @@ gupnp_dlna_container_information_get_packet_size
 }
 
 /**
- * gupnp_dlna_container_information_get_profile:
+ * gupnp_dlna_container_information_get_profile: (skip)
  * @info: A #GUPnPDLNAContainerInformation object.
  *
  * Returns: A profile.
@@ -163,7 +162,7 @@ gupnp_dlna_container_information_get_profile
 }
 
 /**
- * gupnp_dlna_container_information_is_system_stream:
+ * gupnp_dlna_container_information_is_system_stream: (skip)
  * @info: A #GUPnPDLNAContainerInformation object.
  *
  * Returns: Whether it is system stream.
@@ -189,7 +188,7 @@ gupnp_dlna_container_information_is_system_stream
 }
 
 /**
- * gupnp_dlna_container_information_get_variant:
+ * gupnp_dlna_container_information_get_variant: (skip)
  * @info: A #GUPnPDLNAContainerInformation object.
  *
  * Returns: A variant.
@@ -215,7 +214,7 @@ gupnp_dlna_container_information_get_variant
 }
 
 /**
- * gupnp_dlna_container_information_get_mime:
+ * gupnp_dlna_container_information_get_mime: (skip)
  * @info: A #GUPnPDLNAContainerInformation object.
  *
  * Returns: A MIME type.
diff --git a/libgupnp-dlna/gupnp-dlna-g-values.c b/libgupnp-dlna/gupnp-dlna-g-values.c
index 40478f6..d2238a7 100644
--- a/libgupnp-dlna/gupnp-dlna-g-values.c
+++ b/libgupnp-dlna/gupnp-dlna-g-values.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2012 Intel Corporation.
+ * Copyright (C) 2012, 2013 Intel Corporation.
  *
  * Authors: Krzesimir Nowak <krnowak openismus com>
  *
@@ -67,6 +67,12 @@ gupnp_dlna_int_range_new (gint min,
         return range;
 }
 
+/**
+ * gupnp_dlna_fraction_copy:
+ * @fraction: (transfer none): A fraction to copy.
+ *
+ * Returns: (transfer full): A copy of @fraction.
+ */
 GUPnPDLNAFraction *
 gupnp_dlna_fraction_copy (GUPnPDLNAFraction *fraction)
 {
@@ -82,6 +88,12 @@ gupnp_dlna_fraction_copy (GUPnPDLNAFraction *fraction)
         return dup;
 }
 
+/**
+ * gupnp_dlna_fraction_free:
+ * @fraction: A fraction to free.
+ *
+ * Frees @fraction.
+ */
 void
 gupnp_dlna_fraction_free (GUPnPDLNAFraction *fraction)
 {
@@ -91,6 +103,12 @@ gupnp_dlna_fraction_free (GUPnPDLNAFraction *fraction)
         g_slice_free (GUPnPDLNAFraction, fraction);
 }
 
+/**
+ * gupnp_dlna_fraction_get_numerator:
+ * @fraction: A fraction.
+ *
+ * Returns: @fraction's numerator.
+ */
 gint
 gupnp_dlna_fraction_get_numerator (GUPnPDLNAFraction *fraction)
 {
@@ -99,6 +117,12 @@ gupnp_dlna_fraction_get_numerator (GUPnPDLNAFraction *fraction)
         return fraction->numerator;
 }
 
+/**
+ * gupnp_dlna_fraction_get_denominator:
+ * @fraction: A fraction.
+ *
+ * Returns: @fraction's denominator.
+ */
 gint
 gupnp_dlna_fraction_get_denominator (GUPnPDLNAFraction *fraction)
 {
@@ -107,6 +131,12 @@ gupnp_dlna_fraction_get_denominator (GUPnPDLNAFraction *fraction)
         return fraction->denominator;
 }
 
+/**
+ * gupnp_dlna_fraction_range_copy:
+ * @range: (transfer none): A range to copy.
+ *
+ * Returns: (transfer full): A copy of @range.
+ */
 GUPnPDLNAFractionRange *
 gupnp_dlna_fraction_range_copy (GUPnPDLNAFractionRange *range)
 {
@@ -118,6 +148,12 @@ gupnp_dlna_fraction_range_copy (GUPnPDLNAFractionRange *range)
                                          gupnp_dlna_fraction_copy (range->max));
 }
 
+/**
+ * gupnp_dlna_fraction_range_free:
+ * @range: A range to free.
+ *
+ * Frees @range.
+ */
 void
 gupnp_dlna_fraction_range_free (GUPnPDLNAFractionRange *range)
 {
@@ -129,6 +165,12 @@ gupnp_dlna_fraction_range_free (GUPnPDLNAFractionRange *range)
         g_slice_free (GUPnPDLNAFractionRange, range);
 }
 
+/**
+ * gupnp_dlna_fraction_range_get_min:
+ * @range: A range.
+ *
+ * Returns: (transfer none): Minimum value of @range.
+ */
 GUPnPDLNAFraction *
 gupnp_dlna_fraction_range_get_min (GUPnPDLNAFractionRange *range)
 {
@@ -137,6 +179,12 @@ gupnp_dlna_fraction_range_get_min (GUPnPDLNAFractionRange *range)
         return range->min;
 }
 
+/**
+ * gupnp_dlna_fraction_range_get_max:
+ * @range: A range.
+ *
+ * Returns: (transfer none): Maximum value of @range.
+ */
 GUPnPDLNAFraction *
 gupnp_dlna_fraction_range_get_max (GUPnPDLNAFractionRange *range)
 {
@@ -145,6 +193,12 @@ gupnp_dlna_fraction_range_get_max (GUPnPDLNAFractionRange *range)
         return range->max;
 }
 
+/**
+ * gupnp_dlna_int_range_copy:
+ * @range: (transfer none): A range to copy.
+ *
+ * Returns: (transfer full): A copy of @range.
+ */
 GUPnPDLNAIntRange *
 gupnp_dlna_int_range_copy (GUPnPDLNAIntRange *range)
 {
@@ -154,6 +208,12 @@ gupnp_dlna_int_range_copy (GUPnPDLNAIntRange *range)
         return gupnp_dlna_int_range_new (range->min, range->max);
 }
 
+/**
+ * gupnp_dlna_int_range_free:
+ * @range: A range to free.
+ *
+ * Frees @range.
+ */
 void
 gupnp_dlna_int_range_free (GUPnPDLNAIntRange *range)
 {
@@ -163,6 +223,12 @@ gupnp_dlna_int_range_free (GUPnPDLNAIntRange *range)
         g_slice_free (GUPnPDLNAIntRange, range);
 }
 
+/**
+ * gupnp_dlna_int_range_get_min:
+ * @range: A range.
+ *
+ * Returns: Minimum value of @range.
+ */
 gint
 gupnp_dlna_int_range_get_min (GUPnPDLNAIntRange *range)
 {
@@ -171,6 +237,12 @@ gupnp_dlna_int_range_get_min (GUPnPDLNAIntRange *range)
         return range->min;
 }
 
+/**
+ * gupnp_dlna_int_range_get_max:
+ * @range: A range.
+ *
+ * Returns: Maximum value of @range.
+ */
 gint
 gupnp_dlna_int_range_get_max (GUPnPDLNAIntRange *range)
 {
diff --git a/libgupnp-dlna/gupnp-dlna-image-information.c b/libgupnp-dlna/gupnp-dlna-image-information.c
index 9551cc3..9d23038 100644
--- a/libgupnp-dlna/gupnp-dlna-image-information.c
+++ b/libgupnp-dlna/gupnp-dlna-image-information.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2012 Intel Corporation.
+ * Copyright (C) 2012, 2013 Intel Corporation.
  *
  * Authors: Krzesimir Nowak <krnowak openismus com>
  *
@@ -23,6 +23,8 @@
  * SECTION:gupnp-dlna-image-information
  * @short_description: Base class representing image metadata needed
  * for DLNA profiles matching.
+ * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
+ * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  *
  * #GUPnPDLNAImageInformation holds all image metadatas important for
  * matching profiles. Note that it does not mean all data should be
@@ -41,9 +43,6 @@
  * Note that gupnp_dlna_image_information_get_mime() should always
  * return a set value. Otherwise it is highly probably that the file
  * will not match against any DLNA profile.
- *
- * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
- * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  */
 
 #include "gupnp-dlna-image-information.h"
@@ -81,7 +80,7 @@ gupnp_dlna_image_information_init (GUPnPDLNAImageInformation *info)
 }
 
 /**
- * gupnp_dlna_image_information_get_depth:
+ * gupnp_dlna_image_information_get_depth: (skip)
  * @info: A #GUPnPDLNAImageInformation object.
  *
  * Returns: A depth of an image.
@@ -106,7 +105,7 @@ gupnp_dlna_image_information_get_depth (GUPnPDLNAImageInformation *info)
 }
 
 /**
- * gupnp_dlna_image_information_get_height:
+ * gupnp_dlna_image_information_get_height: (skip)
  * @info: A #GUPnPDLNAImageInformation object.
  *
  * Returns: A height of an image.
@@ -131,7 +130,7 @@ gupnp_dlna_image_information_get_height (GUPnPDLNAImageInformation *info)
 }
 
 /**
- * gupnp_dlna_image_information_get_width:
+ * gupnp_dlna_image_information_get_width: (skip)
  * @info: A #GUPnPDLNAImageInformation object.
  *
  * Returns: A width of an image.
@@ -156,7 +155,7 @@ gupnp_dlna_image_information_get_width (GUPnPDLNAImageInformation *info)
 }
 
 /**
- * gupnp_dlna_image_information_get_mime:
+ * gupnp_dlna_image_information_get_mime: (skip)
  * @info: A #GUPnPDLNAImageInformation object.
  *
  * Returns: A MIME type of an image.
diff --git a/libgupnp-dlna/gupnp-dlna-profile.c b/libgupnp-dlna/gupnp-dlna-profile.c
index f21fe4d..65591bc 100644
--- a/libgupnp-dlna/gupnp-dlna-profile.c
+++ b/libgupnp-dlna/gupnp-dlna-profile.c
@@ -1,6 +1,6 @@
 /*
  * Copyright (C) 2010 Nokia Corporation.
- * Copyright (C) 2012 Intel Corporation.
+ * Copyright (C) 2012, 2013 Intel Corporation.
  *
  * Authors: Arun Raghavan <arun raghavan collabora co uk>
  *          Krzesimir Nowak <krnowak openismus com>
@@ -64,8 +64,8 @@ gupnp_dlna_profile_get_property (GObject    *object,
                                  GValue     *value,
                                  GParamSpec *pspec)
 {
-        GUPnPDLNAProfile *self = GUPNP_DLNA_PROFILE (object);
-        GUPnPDLNAProfilePrivate *priv = self->priv;
+        GUPnPDLNAProfile *profile = GUPNP_DLNA_PROFILE (object);
+        GUPnPDLNAProfilePrivate *priv = profile->priv;
 
         switch (property_id) {
         case PROP_DLNA_NAME:
@@ -119,8 +119,8 @@ gupnp_dlna_profile_set_property (GObject      *object,
                                  const GValue *value,
                                  GParamSpec   *pspec)
 {
-        GUPnPDLNAProfile *self = GUPNP_DLNA_PROFILE (object);
-        GUPnPDLNAProfilePrivate *priv = self->priv;
+        GUPnPDLNAProfile *profile = GUPNP_DLNA_PROFILE (object);
+        GUPnPDLNAProfilePrivate *priv = profile->priv;
 
         switch (property_id) {
         case PROP_DLNA_NAME:
@@ -167,8 +167,8 @@ gupnp_dlna_profile_set_property (GObject      *object,
 static void
 gupnp_dlna_profile_finalize (GObject *object)
 {
-        GUPnPDLNAProfile *self = GUPNP_DLNA_PROFILE (object);
-        GUPnPDLNAProfilePrivate *priv = self->priv;
+        GUPnPDLNAProfile *profile = GUPNP_DLNA_PROFILE (object);
+        GUPnPDLNAProfilePrivate *priv = profile->priv;
 
         g_free (priv->name);
         g_free (priv->mime);
@@ -269,9 +269,9 @@ gupnp_dlna_profile_class_init (GUPnPDLNAProfileClass *klass)
 }
 
 static void
-gupnp_dlna_profile_init (GUPnPDLNAProfile *self)
+gupnp_dlna_profile_init (GUPnPDLNAProfile *profile)
 {
-        GUPnPDLNAProfilePrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE (self,
+        GUPnPDLNAProfilePrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE (profile,
                                                   GUPNP_TYPE_DLNA_PROFILE,
                                                   GUPnPDLNAProfilePrivate);
 
@@ -282,7 +282,7 @@ gupnp_dlna_profile_init (GUPnPDLNAProfile *self)
         priv->container_restrictions = NULL;
         priv->image_restrictions = NULL;
         priv->video_restrictions = NULL;
-        self->priv = priv;
+        profile->priv = priv;
 }
 
 /**
@@ -327,37 +327,72 @@ gupnp_dlna_profile_get_extended (GUPnPDLNAProfile *profile)
         return profile->priv->extended;
 }
 
+/**
+ * gupnp_dlna_profile_get_audio_restrictions:
+ * @profile: (transfer none): A profile.
+ *
+ * Gets a list of audio restrictions.
+ *
+ * Returns: (transfer none) (element-type GUPnPDLNARestriction): Audio
+ * restrictions. Do not modify.
+ */
 GList *
-gupnp_dlna_profile_get_audio_restrictions (GUPnPDLNAProfile *self)
+gupnp_dlna_profile_get_audio_restrictions (GUPnPDLNAProfile *profile)
 {
-        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (self), NULL);
+        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (profile), NULL);
 
-        return self->priv->audio_restrictions;
+        return profile->priv->audio_restrictions;
 }
 
+/**
+ * gupnp_dlna_profile_get_container_restrictions:
+ * @profile: (transfer none): A profile.
+ *
+ * Gets a list of container restrictions.
+ *
+ * Returns: (transfer none) (element-type GUPnPDLNARestriction):
+ * Container restrictions. Do not modify.
+ */
 GList *
-gupnp_dlna_profile_get_container_restrictions
-                                        (GUPnPDLNAProfile *self)
+gupnp_dlna_profile_get_container_restrictions (GUPnPDLNAProfile *profile)
 {
-        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (self), NULL);
+        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (profile), NULL);
 
-        return self->priv->container_restrictions;
+        return profile->priv->container_restrictions;
 }
 
+/**
+ * gupnp_dlna_profile_get_image_restrictions:
+ * @profile: (transfer none): A profile.
+ *
+ * Gets a list of image restrictions.
+ *
+ * Returns: (transfer none) (element-type GUPnPDLNARestriction): Image
+ * restrictions. Do not modify.
+ */
 GList *
-gupnp_dlna_profile_get_image_restrictions (GUPnPDLNAProfile *self)
+gupnp_dlna_profile_get_image_restrictions (GUPnPDLNAProfile *profile)
 {
-        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (self), NULL);
+        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (profile), NULL);
 
-        return self->priv->image_restrictions;
+        return profile->priv->image_restrictions;
 }
 
+/**
+ * gupnp_dlna_profile_get_video_restrictions:
+ * @profile: (transfer none): A profile.
+ *
+ * Gets a list of video restrictions.
+ *
+ * Returns: (transfer none) (element-type GUPnPDLNARestriction): Video
+ * restrictions. Do not modify.
+ */
 GList *
-gupnp_dlna_profile_get_video_restrictions (GUPnPDLNAProfile *self)
+gupnp_dlna_profile_get_video_restrictions (GUPnPDLNAProfile *profile)
 {
-        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (self), NULL);
+        g_return_val_if_fail (GUPNP_IS_DLNA_PROFILE (profile), NULL);
 
-        return self->priv->video_restrictions;
+        return profile->priv->video_restrictions;
 }
 
 GUPnPDLNAProfile *
diff --git a/libgupnp-dlna/gupnp-dlna-profile.h b/libgupnp-dlna/gupnp-dlna-profile.h
index e63bb97..d7eeaa2 100644
--- a/libgupnp-dlna/gupnp-dlna-profile.h
+++ b/libgupnp-dlna/gupnp-dlna-profile.h
@@ -89,16 +89,16 @@ gboolean
 gupnp_dlna_profile_get_extended (GUPnPDLNAProfile *profile);
 
 GList *
-gupnp_dlna_profile_get_container_restrictions (GUPnPDLNAProfile *self);
+gupnp_dlna_profile_get_container_restrictions (GUPnPDLNAProfile *profile);
 
 GList *
-gupnp_dlna_profile_get_audio_restrictions (GUPnPDLNAProfile *self);
+gupnp_dlna_profile_get_audio_restrictions (GUPnPDLNAProfile *profile);
 
 GList *
-gupnp_dlna_profile_get_image_restrictions (GUPnPDLNAProfile *self);
+gupnp_dlna_profile_get_image_restrictions (GUPnPDLNAProfile *profile);
 
 GList *
-gupnp_dlna_profile_get_video_restrictions (GUPnPDLNAProfile *self);
+gupnp_dlna_profile_get_video_restrictions (GUPnPDLNAProfile *profile);
 
 G_END_DECLS
 
diff --git a/libgupnp-dlna/gupnp-dlna-restriction.c b/libgupnp-dlna/gupnp-dlna-restriction.c
index c31e150..5f67488 100644
--- a/libgupnp-dlna/gupnp-dlna-restriction.c
+++ b/libgupnp-dlna/gupnp-dlna-restriction.c
@@ -49,6 +49,12 @@ gupnp_dlna_restriction_new (const gchar *mime)
         return restriction;
 }
 
+/**
+ * gupnp_dlna_restriction_copy:
+ * @restriction: (transfer none): A restriction to copy.
+ *
+ * Returns: (transfer full): A copy of @restriction.
+ */
 GUPnPDLNARestriction *
 gupnp_dlna_restriction_copy (GUPnPDLNARestriction *restriction)
 {
@@ -76,6 +82,12 @@ gupnp_dlna_restriction_copy (GUPnPDLNARestriction *restriction)
         return dup;
 }
 
+/**
+ * gupnp_dlna_restriction_free:
+ * @restriction: A restriction to free.
+ *
+ * Frees @restriction.
+ */
 void
 gupnp_dlna_restriction_free (GUPnPDLNARestriction *restriction)
 {
@@ -135,6 +147,13 @@ gupnp_dlna_restriction_merge (GUPnPDLNARestriction *restriction,
         gupnp_dlna_restriction_free (merged);
 }
 
+/**
+ * gupnp_dlna_restriction_is_empty:
+ * @restriction: (transfer none): A restriction.
+ *
+ * Returns: %TRUE if @restriction is empty and has no MIME type,
+ * otherwise %FALSE.
+ */
 gboolean
 gupnp_dlna_restriction_is_empty (GUPnPDLNARestriction *restriction)
 {
@@ -144,6 +163,15 @@ gupnp_dlna_restriction_is_empty (GUPnPDLNARestriction *restriction)
                 g_hash_table_size (restriction->entries) == 0);
 }
 
+/**
+ * gupnp_dlna_restriction_to_string:
+ * @restriction: (transfer none): A restriction.
+ *
+ * Creates a string representation of @restriction.
+ *
+ * Returns: (transfer full): A string representation of
+ * @restriction. Free with g_free() when not needed.
+ */
 gchar *
 gupnp_dlna_restriction_to_string (GUPnPDLNARestriction *restriction)
 {
@@ -169,6 +197,14 @@ gupnp_dlna_restriction_to_string (GUPnPDLNARestriction *restriction)
         return g_string_free (str, FALSE);
 }
 
+/**
+ * gupnp_dlna_restriction_get_mime:
+ * @restriction: (transfer none): A restriction.
+ *
+ * Gets @restriction's MIME type.
+ *
+ * Returns: (transfer none): MIME type. Do not modify.
+ */
 const gchar *
 gupnp_dlna_restriction_get_mime (GUPnPDLNARestriction *restriction)
 {
@@ -177,6 +213,16 @@ gupnp_dlna_restriction_get_mime (GUPnPDLNARestriction *restriction)
         return restriction->mime;
 }
 
+/**
+ * gupnp_dlna_restriction_get_entries:
+ * @restriction: (transfer none): A restriction.
+ *
+ * Gets @restriction's entries. It is a string to #GUPnPDLNAValueList
+ * mapping.
+ *
+ * Returns: (transfer none) (element-type utf8 GUPnPDLNAValueList):
+ * Entries. Do not modify.
+ */
 GHashTable *
 gupnp_dlna_restriction_get_entries (GUPnPDLNARestriction *restriction)
 {
diff --git a/libgupnp-dlna/gupnp-dlna-value-list.c b/libgupnp-dlna/gupnp-dlna-value-list.c
index 70186fc..0582978 100644
--- a/libgupnp-dlna/gupnp-dlna-value-list.c
+++ b/libgupnp-dlna/gupnp-dlna-value-list.c
@@ -61,6 +61,12 @@ free_value_list (GUPnPDLNAValueList *list)
         }
 }
 
+/**
+ * gupnp_dlna_value_list_free:
+ * @list: A list to free.
+ *
+ * Frees the value list.
+ */
 void
 gupnp_dlna_value_list_free (GUPnPDLNAValueList *list)
 {
@@ -134,6 +140,12 @@ gupnp_dlna_value_list_add_range (GUPnPDLNAValueList *list,
         return FALSE;
 }
 
+/**
+ * gupnp_dlna_value_list_copy:
+ * @list: (transfer none): A list to copy.
+ *
+ * Returns: (transfer full): A copy of @list.
+ */
 GUPnPDLNAValueList *
 gupnp_dlna_value_list_copy (GUPnPDLNAValueList *list)
 {
@@ -196,6 +208,12 @@ gupnp_dlna_value_list_is_superset (GUPnPDLNAValueList *list,
         return FALSE;
 }
 
+/**
+ * gupnp_dlna_value_list_is_empty:
+ * @list: (transfer none): A list.
+ *
+ * Returns: %TRUE if @list is empty, otherwise %FALSE.
+ */
 gboolean
 gupnp_dlna_value_list_is_empty (GUPnPDLNAValueList *value_list)
 {
@@ -234,6 +252,15 @@ list_to_string (GUPnPDLNAValueList *value_list)
         return str;
 }
 
+/**
+ * gupnp_dlna_value_list_to_string:
+ * @list: (transfer none): A list.
+ *
+ * Creates a string representation of @list.
+ *
+ * Returns: (transfer full): A string representation of @list. Free
+ * with g_free() when not needed.
+ */
 gchar *
 gupnp_dlna_value_list_to_string (GUPnPDLNAValueList *value_list)
 {
@@ -277,6 +304,17 @@ gupnp_dlna_value_list_sort_items (GUPnPDLNAValueList *value_list)
         }
 }
 
+/**
+ * gupnp_dlna_value_list_get_g_values:
+ * @list: (transfer none): A list.
+ *
+ * Gets a list of #GValues. #GValues can be of types #G_TYPE_BOOLEAN,
+ * #G_TYPE_INT, #G_TYPE_STRING, #GUPNP_TYPE_DLNA_FRACTION,
+ * #GUPNP_TYPE_DLNA_FRACTION_RANGE or #GUPNP_TYPE_DLNA_INT_RANGE.
+ *
+ * Returns: (transfer full) (element-type GValue): A list. Free it
+ * with g_list_free_full() with g_free().
+ */
 GList *
 gupnp_dlna_value_list_get_g_values (GUPnPDLNAValueList *list)
 {
diff --git a/libgupnp-dlna/gupnp-dlna-value.c b/libgupnp-dlna/gupnp-dlna-value.c
index 5343c96..ade3554 100644
--- a/libgupnp-dlna/gupnp-dlna-value.c
+++ b/libgupnp-dlna/gupnp-dlna-value.c
@@ -433,10 +433,10 @@ gupnp_dlna_value_to_g_value (GUPnPDLNAValue     *base,
         g_return_val_if_fail (base->vtable != NULL, NULL);
         g_return_val_if_fail (base->vtable->to_g_value != NULL, NULL);
 
-        g_value = g_slice_new0 (GValue);
+        g_value = g_new0 (GValue, 1);
 
         if (base->vtable->to_g_value (base, type, g_value)) {
-                g_slice_free (GValue, g_value);
+                g_free (g_value);
                 g_value = NULL;
         }
 
diff --git a/libgupnp-dlna/gupnp-dlna-video-information.c b/libgupnp-dlna/gupnp-dlna-video-information.c
index eff3a92..e1d6c06 100644
--- a/libgupnp-dlna/gupnp-dlna-video-information.c
+++ b/libgupnp-dlna/gupnp-dlna-video-information.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2012 Intel Corporation.
+ * Copyright (C) 2012, 2013 Intel Corporation.
  *
  * Authors: Krzesimir Nowak <krnowak openismus com>
  *
@@ -23,6 +23,8 @@
  * SECTION:gupnp-dlna-video-information
  * @short_description: Base class representing video metadata needed
  * for DLNA profiles matching.
+ * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
+ * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  *
  * #GUPnPDLNAVideoInformation holds all video metadatas important for
  * matching profiles. Note that it does not mean all data should be
@@ -42,9 +44,6 @@
  * Note that gupnp_dlna_video_information_get_mime() should always
  * return a set value. Otherwise it is highly probably that the file
  * will not match against any DLNA profile.
- *
- * @see_also: #GUPnPDLNABoolValue, #GUPnPDLNAFractionValue,
- * #GUPnPDLNAIntValue, #GUPnPDLNAStringValue
  */
 
 #include "gupnp-dlna-video-information.h"
@@ -89,7 +88,7 @@ gupnp_dlna_video_information_init (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_bitrate:
+ * gupnp_dlna_video_information_get_bitrate: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A bitrate.
@@ -114,7 +113,7 @@ gupnp_dlna_video_information_get_bitrate (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_framerate:
+ * gupnp_dlna_video_information_get_framerate: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A framerate.
@@ -139,7 +138,7 @@ gupnp_dlna_video_information_get_framerate (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_height:
+ * gupnp_dlna_video_information_get_height: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A height.
@@ -164,7 +163,7 @@ gupnp_dlna_video_information_get_height (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_is_interlaced:
+ * gupnp_dlna_video_information_is_interlaced: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: Whether video is interlaced.
@@ -189,7 +188,7 @@ gupnp_dlna_video_information_is_interlaced (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_level:
+ * gupnp_dlna_video_information_get_level: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A level.
@@ -214,7 +213,7 @@ gupnp_dlna_video_information_get_level (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_mpeg_version:
+ * gupnp_dlna_video_information_get_mpeg_version: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: An MPEG version.
@@ -239,7 +238,7 @@ gupnp_dlna_video_information_get_mpeg_version (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_pixel_aspect_ratio:
+ * gupnp_dlna_video_information_get_pixel_aspect_ratio: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A pixel-aspect-ratio.
@@ -265,7 +264,7 @@ gupnp_dlna_video_information_get_pixel_aspect_ratio
 }
 
 /**
- * gupnp_dlna_video_information_get_profile:
+ * gupnp_dlna_video_information_get_profile: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A profile.
@@ -290,7 +289,7 @@ gupnp_dlna_video_information_get_profile (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_is_system_stream:
+ * gupnp_dlna_video_information_is_system_stream: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: Whether it is a system stream.
@@ -315,7 +314,7 @@ gupnp_dlna_video_information_is_system_stream (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_width:
+ * gupnp_dlna_video_information_get_width: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A width.
@@ -340,7 +339,7 @@ gupnp_dlna_video_information_get_width (GUPnPDLNAVideoInformation *info)
 }
 
 /**
- * gupnp_dlna_video_information_get_mime:
+ * gupnp_dlna_video_information_get_mime: (skip)
  * @info: A #GUPnPDLNAVideoInformation object.
  *
  * Returns: A MIME type.



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]