From 886dd1b908e034b60b8545be365de5b3ce00052b Mon Sep 17 00:00:00 2001
From: Martin Pulec <martin.pulec@cesnet.cz>
Date: Tue, 18 Jan 2022 15:33:37 +0100
Subject: [PATCH] Video compress: improved documentation

---
 src/video_compress.cpp | 14 ++++++++++++--
 src/video_compress.h   | 22 +++++++++++++++-------
 2 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/src/video_compress.cpp b/src/video_compress.cpp
index f87ff87ec..74f377664 100644
--- a/src/video_compress.cpp
+++ b/src/video_compress.cpp
@@ -325,11 +325,16 @@ static bool check_state_count(unsigned tile_count, struct compress_state *proxy)
 }
 
 /**
- * @brief Compressses frame
+ * Puts frame for compression to queue and returns, result must be queried by
+ * compress_pop().
+ *
+ * In case of error, no frame is returned.
+ *
+ * Accepts poison pill (shared_ptr<video_frame>{nullptr}) and passes it over the queue
+ * to compress_pop().
  *
  * @param proxy        compress state
  * @param frame        uncompressed frame to be compressed
- * @return             compressed frame, may be NULL if compression failed
  */
 void compress_frame(struct compress_state *proxy, shared_ptr<video_frame> frame)
 {
@@ -590,6 +595,11 @@ void compress_state_real::async_consumer(struct compress_state *s)
 }
 } // end of anonymous namespace
 
+/**
+ * @returns compressed frame previously enqueued by compress_frame(). If an error
+ * occurs function doesn't return.
+ * @retval shared_ptr<video_frame>{} poison pill passed previously to compress_frame()
+ */
 shared_ptr<video_frame> compress_pop(struct compress_state *proxy)
 {
         if(!proxy)
diff --git a/src/video_compress.h b/src/video_compress.h
index 101f46654..126f6e26f 100644
--- a/src/video_compress.h
+++ b/src/video_compress.h
@@ -79,6 +79,9 @@ struct module;
 
 extern struct module compress_init_noerr;
 
+//
+// Begins external API for video compression use
+//
 /**
  * @brief Initializes video compression
  * 
@@ -88,18 +91,26 @@ extern struct module compress_init_noerr;
  */
 typedef struct module *(*compress_init_t)(struct module *parent,
                 const char *cfg);
-
+// documented at definition
 void show_compress_help(bool full);
+// documented at definition
 int compress_init(struct module *parent, const char *config_string, struct compress_state **);
+// documented at definition
 const char *get_compress_name(struct compress_state *);
-
 #ifdef __cplusplus
 }
 #endif
-
 #ifdef __cplusplus
-#include <list>
 #include <memory>
+// documented at definition
+void compress_frame(struct compress_state *, std::shared_ptr<video_frame>);
+// documented at definition
+std::shared_ptr<video_frame> compress_pop(struct compress_state *);
+
+//
+// Begins API for individual video compression modules
+//
+#include <list>
 #include <string>
 #include <vector>
 
@@ -159,7 +170,6 @@ typedef void (*compress_tile_async_push_t)(struct module *state, std::shared_ptr
  */
 typedef  std::shared_ptr<video_frame> (*compress_tile_async_pop_t)(struct module *state);
 
-void compress_frame(struct compress_state *, std::shared_ptr<video_frame>);
 
 struct compress_preset {
         struct compress_prop {
@@ -239,8 +249,6 @@ struct video_compress_info {
         compress_module_info (*get_module_info)();
 };
 
-std::shared_ptr<video_frame> compress_pop(struct compress_state *);
-
 #endif // __cplusplus
 
 #endif /* __video_compress_h */