com init documenation updates (incl deck)

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)
 {

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);

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

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);