encoding-target: Add more docs regarding categories

gst-libs/gst/pbutils/encoding-target.c

@@ -133,7 +133,8 @@ gst_encoding_target_get_name (GstEncodingTarget * target)
  *
  * Since: 0.10.32
  *
- * Returns: (transfer none): The category of the @target.
+ * Returns: (transfer none): The category of the @target. For example:
+ * #GST_ENCODING_CATEGORY_DEVICE.
  */
 const gchar *
 gst_encoding_target_get_category (GstEncodingTarget * target)
@@ -238,7 +239,7 @@ validate_name (const gchar * name)
  * gst_encoding_target_new:
  * @name: The name of the target.
  * @category: (transfer none): The name of the category to which this @target
- * belongs.
+ * belongs. For example: #GST_ENCODING_CATEGORY_DEVICE.
  * @description: (transfer none): A description of #GstEncodingTarget in the
  * current locale.
  * @profiles: (transfer none) (element-type Gst.EncodingProfile): A #GList of
@@ -250,6 +251,10 @@ validate_name (const gchar * name)
  * first character, followed by either lowercase ASCII letters, digits or
  * hyphens ('-').
  *
+ * The @category *should* be one of the existing well-defined categories, like
+ * #GST_ENCODING_CATEGORY_DEVICE, but it *can* be a application or user specific
+ * category if needed.
+ *
  * Since: 0.10.32
  *
  * Returns: (transfer full): The newly created #GstEncodingTarget or %NULL if
@@ -305,7 +310,8 @@ invalid_category:
  * @target: the #GstEncodingTarget to add a profile to
  * @profile: (transfer full): the #GstEncodingProfile to add
  *
- * Adds the given @profile to the @target.
+ * Adds the given @profile to the @target. Each added profile must have
+ * a unique name within the profile.
  *
  * The @target will steal a reference to the @profile. If you wish to use
  * the profile after calling this method, you should increase its reference
@@ -783,7 +789,8 @@ gst_encoding_target_subload (gchar * path, const gchar * category,
 /**
  * gst_encoding_target_load:
  * @name: the name of the #GstEncodingTarget to load.
- * @category: (allow-none): the name of the target category. Can be %NULL
+ * @category: (allow-none): the name of the target category, like
+ * #GST_ENCODING_CATEGORY_DEVICE. Can be %NULL
  * @error: If an error occured, this field will be filled in.
  *
  * Searches for the #GstEncodingTarget with the given name, loads it

gst-libs/gst/pbutils/encoding-target.h

@@ -32,9 +32,39 @@ G_BEGIN_DECLS
  *
  */
 
+/**
+ * GST_ENCODING_CATEGORY_DEVICE:
+ * #GstEncodingTarget category for device-specific targets.
+ * The name of the target will usually be the contructor and model of the device,
+ * and that target will contain #GstEncodingProfiles suitable for that device.
+ */
 #define GST_ENCODING_CATEGORY_DEVICE		"device"
+
+/**
+ * GST_ENCODING_CATEGORY_ONLINE_SERVICE:
+ * #GstEncodingTarget category for online-services.
+ * The name of the target will usually be the name of the online service
+ * and that target will contain #GstEncodingProfiles suitable for that online
+ * service.
+ */
+
 #define GST_ENCODING_CATEGORY_ONLINE_SERVICE	"online-service"
+
+/**
+ * GST_ENCODING_CATEGORY_STORAGE_EDITING:
+ * #GstEncodingTarget category for storage, archiving and editing targets.
+ * Those targets can be lossless and/or provide very fast random access content.
+ * The name of the target will usually be the container type or editing target,
+ * and that target will contain #GstEncodingProfiles suitable for editing or
+ * storage.
+ */
 #define GST_ENCODING_CATEGORY_STORAGE_EDITING   "storage-editing"
+
+/**
+ * GST_ENCODING_CATEGORY_CAPTURE:
+ * #GstEncodingTarget category for recording and capture.
+ * Targets within this category are optimized for low latency encoding.
+ */
 #define GST_ENCODING_CATEGORY_CAPTURE		"capture"
 
 /**
@@ -42,6 +72,9 @@ G_BEGIN_DECLS
  *
  * Collection of #GstEncodingProfile for a specific target or use-case.
  *
+ * When being stored/loaded, targets come from a specific category, like
+ * #GST_ENCODING_CATEGORY_DEVICE.
+ *
  * Since: 0.10.32
  */
 #define GST_TYPE_ENCODING_TARGET			\