From c82eef425817f2ca0388a33dd3c6548abb1a2ebc Mon Sep 17 00:00:00 2001
From: Martin Pulec <martin.pulec@cesnet.cz>
Date: Mon, 10 Jun 2024 11:05:25 +0200
Subject: [PATCH] com init documenation updates (incl deck)

---
 src/blackmagic_common.cpp | 7 +++++++
 src/blackmagic_common.hpp | 3 +--
 src/utils/windows.c       | 9 +++++++++
 src/utils/windows.h       | 4 ----
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/blackmagic_common.cpp b/src/blackmagic_common.cpp
index ab73d598d..563efdde2 100644
--- a/src/blackmagic_common.cpp
+++ b/src/blackmagic_common.cpp
@@ -161,10 +161,17 @@ std::string get_str_from_bmd_api_str(BMD_STR string)
 }
 
 /**
+ * @param[out] com_initialized  pointer to be passed to decklnk_uninitialize
+ (keeps information if COM needs to be unintialized)
+ * @param coinit  initialize COM - see a note below
  * @note
  * Each successful call (returning non-null pointer) of this function with coinit == true
  * should be followed by com_uninitialize() when done with DeckLink (not when releasing
  * IDeckLinkIterator!), typically on application shutdown.
+ * @note
+ * see @ref com_initialize for details; basically can be false if that the
+ current thread already called CoInitialize[Ex], which now holds - this is
+ currently called from main thread, that already called it in common_init()
  */
 IDeckLinkIterator *create_decklink_iterator(bool *com_initialized, bool verbose, bool coinit)
 {
diff --git a/src/blackmagic_common.hpp b/src/blackmagic_common.hpp
index 771e8bbc5..116c031fc 100644
--- a/src/blackmagic_common.hpp
+++ b/src/blackmagic_common.hpp
@@ -133,9 +133,8 @@ std::string get_str_from_bmd_api_str(BMD_STR string);
 std::string bmd_get_flags_str(BMDDisplayModeFlags flags);
 #endif
 
-///< @param[out] com_initialized - pass a pointer to bool
 IDeckLinkIterator *create_decklink_iterator(bool *com_initialized, bool verbose = true, bool coinit = true);
-///< @param com_initialized - pointer passed to create_decklink_iterator
+/// @param com_initialized - pointer passed to create_decklink_iterator
 void decklink_uninitialize(bool *com_initialized);
 bool blackmagic_api_version_check();
 void print_decklink_version(void);
diff --git a/src/utils/windows.c b/src/utils/windows.c
index 72ac53030..9fb0732bf 100644
--- a/src/utils/windows.c
+++ b/src/utils/windows.c
@@ -48,6 +48,15 @@
 
 #define MOD_NAME "[utils/win] "
 
+/**
+ * @param[out] com_initialize a pointer to a bool that will be passed to
+ * com_uninintialize()
+ * @param[in] err_prefix optional error prefix to be used for eventual error
+ * messges (may be NULL)
+ * @retval true  if either COM already initalized for this thread or this call
+ * initializes COM succesfully
+ * @retval false  COM could not have been initialized
+ */
 bool com_initialize(bool *com_initialized, const char *err_prefix)
 {
 #ifdef _WIN32
diff --git a/src/utils/windows.h b/src/utils/windows.h
index 1d6aead8a..0bdf45b85 100644
--- a/src/utils/windows.h
+++ b/src/utils/windows.h
@@ -73,10 +73,6 @@ extern "C" {
                 case E_INVALIDARG: errptr = "One or more arguments are not valid"; break; \
         }
 
-/**
- * @param[out] com_initialize a pointer to a bool that will be passed to com_uninintialize()
- * @param[in] err_prefix optional error prefix to be used for eventual error messges (may be NULL)
- */
 bool com_initialize(bool *com_initialized, const char *err_prefix);
 ///< @param com_initialized - pointer passed to com_initialize (or create_com_iterator)
 void com_uninitialize(bool *com_initialized);