From bff04a1396189fbecea7ef7f3d50331d09bc89cf Mon Sep 17 00:00:00 2001
From: Thibault Saunier <thibault.saunier@osg.samsung.com>
Date: Wed, 21 Dec 2016 10:02:31 -0300
Subject: [PATCH] pbutils: Add documentation about encoding targets

---
 gst-libs/gst/pbutils/encoding-profile.c | 57 +++++++++++++++++++++++++
 gst-libs/gst/pbutils/encoding-target.c  | 45 +------------------
 2 files changed, 58 insertions(+), 44 deletions(-)

diff --git a/gst-libs/gst/pbutils/encoding-profile.c b/gst-libs/gst/pbutils/encoding-profile.c
index 4aea4d179d..3418162b7d 100644
--- a/gst-libs/gst/pbutils/encoding-profile.c
+++ b/gst-libs/gst/pbutils/encoding-profile.c
@@ -222,6 +222,63 @@
  *
  * ...
  * ]|
+ *
+ * # Encoding Target
+ *
+ * On top of the notion of profiles, we implement the notion of EncodingTarget.
+ * Encoding Targets are basically a higher level of abstraction to define formats
+ * for specific target types. Those can define several GstEncodingProfiles with
+ * different names, for example one for transcoding in full HD, another one for
+ * low res, etc.. which are defined in the same encoding target.
+ *
+ * Basically if you wan to encode a stream to send it to, say, youtube you should
+ * have a Youtube encoding target defined in the "online-service" category.
+ *
+ * ## Encoding target serialization format
+ *
+ * Encoding targets are serialized in a KeyFile like files.
+ *
+ * |[
+ * [GStreamer Encoding Target]
+ * name : <name>
+ * category : <category>
+ * \description : <description> #translatable
+ *
+ * [profile-<profile1name>]
+ * name : <name>
+ * \description : <description> #optional
+ * format : <format>
+ * preset : <preset>
+ *
+ * [streamprofile-<id>]
+ * parent : <encodingprofile.name>[,<encodingprofile.name>..]
+ * \type : <type> # "audio", "video", "text"
+ * format : <format>
+ * preset : <preset>
+ * restriction : <restriction>
+ * presence : <presence>
+ * pass : <pass>
+ * variableframerate : <variableframerate>
+ * ]|
+ *
+ * # Location of encoding target files
+ *
+ * $GST_DATADIR/gstreamer-GST_API_VERSION/encoding-profile
+ * $HOME/gstreamer-GST_API_VERSION/encoding-profile
+ *
+ * There also is a GST_ENCODING_TARGET_PATH environment variable
+ * defining a list of folder containing encoding target files.
+ *
+ * ## Naming convention
+ *
+ * |[
+ *   $(target.category)/$(target.name).gep
+ * ]|
+ *
+ * # Naming restrictions:
+ *
+ *  * lowercase ASCII letter for the first character
+ *  * Same for all other characters + numerics + hyphens
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/gst-libs/gst/pbutils/encoding-target.c b/gst-libs/gst/pbutils/encoding-target.c
index 755a248560..b83e028ebe 100644
--- a/gst-libs/gst/pbutils/encoding-target.c
+++ b/gst-libs/gst/pbutils/encoding-target.c
@@ -27,50 +27,7 @@
 #include <string.h>
 #include "encoding-target.h"
 
-/*
- * File format
- *
- * GKeyFile style.
- *
- * [GStreamer Encoding Target]
- * name : <name>
- * category : <category>
- * description : <description> #translatable
- *
- * [profile-<profile1name>]
- * name : <name>
- * description : <description> #optional
- * format : <format>
- * preset : <preset>
- *
- * [streamprofile-<id>]
- * parent : <encodingprofile.name>[,<encodingprofile.name>..]
- * type : <type> # "audio", "video", "text"
- * format : <format>
- * preset : <preset>
- * restriction : <restriction>
- * presence : <presence>
- * pass : <pass>
- * variableframerate : <variableframerate>
- *  */
-
-/*
- * Location of profile files
- *
- * $GST_DATADIR/gstreamer-GST_API_VERSION/encoding-profile
- * $HOME/gstreamer-GST_API_VERSION/encoding-profile
- *
- * There also is a GST_ENCODING_TARGET_PATH environment variable
- * defining a list of folder containing encoding target files.
- *
- * Naming convention
- *   $(target.category)/$(target.name).gep
- *
- * Naming restrictions:
- *  lowercase ASCII letter for the first character
- *  Same for all other characters + numerics + hyphens
- */
-
+/* Documented in encoding-profile.c */
 
 #define GST_ENCODING_TARGET_HEADER "GStreamer Encoding Target"
 #define GST_ENCODING_TARGET_DIRECTORY "encoding-profiles"