docs: Add clarifications

Adds links to release functions for "new/incremented reference".
Extra info on signal handler.
Parameter description on `obs_property_list_add_*` functions, since
their parameter `name` can be confusing and it is unclear which value
is stored in obs_data_t.
Adds clarifications on calldata_ptr.

docs/sphinx/reference-core.rst

@@ -363,7 +363,8 @@ Libobs Objects
 
 .. function:: obs_data_t *obs_save_source(obs_source_t *source)
 
-   :return: A new reference to a source's saved data
+   :return: A new reference to a source's saved data. Use
+            :c:func:`obs_data_release()` to release it when complete.
 
 ---------------------
 
@@ -557,7 +558,8 @@ Primary signal/procedure handlers
 
 .. function:: signal_handler_t *obs_get_signal_handler(void)
 
-   :return: The primary obs signal handler
+   :return: The primary obs signal handler. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
    See :ref:`core_signal_handler_reference` for more information on
    core signals.
@@ -566,7 +568,8 @@ Primary signal/procedure handlers
 
 .. function:: proc_handler_t *obs_get_proc_handler(void)
 
-   :return: The primary obs procedure handler
+   :return: The primary obs procedure handler. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
 
 .. _core_signal_handler_reference:

docs/sphinx/reference-encoders.rst

@@ -332,7 +332,7 @@ General Encoder Functions
 .. function:: obs_encoder_t *obs_encoder_get_ref(obs_encoder_t *encoder)
 
    Returns an incremented reference if still valid, otherwise returns
-   *NULL*.
+   *NULL*. Release with :c:func:`obs_encoder_release()`.
 
 ---------------------
 
@@ -437,7 +437,8 @@ General Encoder Functions
 .. function:: obs_data_t *obs_encoder_defaults(const char *id)
               obs_data_t *obs_encoder_get_defaults(const obs_encoder_t *encoder)
 
-   :return: An incremented reference to the encoder's default settings
+   :return: An incremented reference to the encoder's default settings.
+            Release with :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -461,19 +462,22 @@ General Encoder Functions
 
 .. function:: obs_data_t *obs_encoder_get_settings(const obs_encoder_t *encoder)
 
-   :return: An incremented reference to the encoder's settings
+   :return: An incremented reference to the encoder's settings. Release with
+            :c:func:`obs_data_release()`.
 
 ---------------------
 
 .. function:: signal_handler_t *obs_encoder_get_signal_handler(const obs_encoder_t *encoder)
 
-   :return: The signal handler of the encoder
+   :return: The signal handler of the encoder. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
 ---------------------
 
 .. function:: proc_handler_t *obs_encoder_get_proc_handler(const obs_encoder_t *encoder)
 
-   :return: The procedure handler of the encoder
+   :return: The procedure handler of the encoder. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
 ---------------------
 

docs/sphinx/reference-frontend-api.rst

@@ -266,7 +266,8 @@ Functions
 
 .. function:: obs_source_t *obs_frontend_get_current_scene(void)
 
-   :return: A new reference to the currently active scene
+   :return: A new reference to the currently active scene. Release with
+            :c:func:`obs_source_release()`.
 
 ---------------------------------------
 
@@ -287,7 +288,8 @@ Functions
 
 .. function:: obs_source_t *obs_frontend_get_current_transition(void)
 
-   :return: A new reference to the currently active transition
+   :return: A new reference to the currently active transition.
+            Release with :c:func:`obs_source_release()`.
 
 ---------------------------------------
 
@@ -612,19 +614,22 @@ Functions
 
 .. function:: obs_output_t *obs_frontend_get_streaming_output(void)
 
-   :return: A new reference to the current streaming output
+   :return: A new reference to the current streaming output.
+            Release with :c:func:`obs_output_release()`.
 
 ---------------------------------------
 
 .. function:: obs_output_t *obs_frontend_get_recording_output(void)
 
-   :return: A new reference to the current srecording output
+   :return: A new reference to the current recording output.
+            Release with :c:func:`obs_output_release()`.
 
 ---------------------------------------
 
 .. function:: obs_output_t *obs_frontend_get_replay_buffer_output(void)
 
-   :return: A new reference to the current replay buffer output
+   :return: A new reference to the current replay buffer output.
+            Release with :c:func:`obs_output_release()`.
 
 ---------------------------------------
 
@@ -650,7 +655,8 @@ Functions
 
 .. function:: obs_service_t *obs_frontend_get_streaming_service(void)
 
-   :return: A new reference to the current streaming service object
+   :return: A new reference to the current streaming service object.
+            Release with :c:func:`obs_service_release()`.
 
 ---------------------------------------
 
@@ -684,7 +690,8 @@ Functions
 .. function:: obs_source_t *obs_frontend_get_current_preview_scene(void)
 
    :return: A new reference to the current preview scene if studio mode
-            is active, or *NULL* if studio mode is not active.
+            is active, or *NULL* if studio mode is not active. Release
+            with :c:func:`obs_source_release()`.
 
 ---------------------------------------
 
@@ -728,7 +735,8 @@ Functions
 
 .. function:: obs_output_t *obs_frontend_get_virtualcam_output(void)
 
-   :return: A new reference to the current virtual camera output
+   :return: A new reference to the current virtual camera output.
+            Release with :c:func:`obs_output_release()`.
 
 ---------------------------------------
 

docs/sphinx/reference-libobs-callback.rst

@@ -22,7 +22,9 @@ handlers or to procedure handlers.
 
 .. function:: void calldata_free(calldata_t *data)
 
-   Frees a calldata structure.
+   Frees a calldata structure. Should only be used if :c:func:`calldata_init()`
+   was used. If the object is received as a callback parameter, this function
+   should not be used.
 
    :param data: Calldata structure
 
@@ -110,7 +112,9 @@ handlers or to procedure handlers.
 
 .. function:: void *calldata_ptr(const calldata_t *data, const char *name)
 
-   Gets a pointer parameter.
+   Gets a pointer parameter. For example, :ref:`core_signal_handler_reference`
+   that have ``ptr source`` as a parameter requires this function to get the
+   pointer, which can be casted to :c:type:`obs_source_t`. Does not have to be freed.
 
    :param data: Calldata structure
    :param name: Parameter name

docs/sphinx/reference-outputs.rst

@@ -345,7 +345,7 @@ General Output Functions
 .. function:: obs_output_t *obs_output_get_ref(obs_output_t *output)
 
    Returns an incremented reference if still valid, otherwise returns
-   *NULL*.
+   *NULL*. Release with :c:func:`obs_output_release()`.
 
 ---------------------
 
@@ -443,7 +443,8 @@ General Output Functions
 
 .. function:: obs_data_t *obs_output_defaults(const char *id)
 
-   :return: An incremented reference to the output's default settings
+   :return: An incremented reference to the output's default settings.
+            Release with :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -488,19 +489,22 @@ General Output Functions
 
 .. function:: obs_data_t *obs_output_get_settings(const obs_output_t *output)
 
-   :return: An incremented reference to the output's settings
+   :return: An incremented reference to the output's settings. Release with
+            :c:func:`obs_data_release()`.
 
 ---------------------
 
 .. function:: signal_handler_t *obs_output_get_signal_handler(const obs_output_t *output)
 
-   :return: The signal handler of the output
+   :return: The signal handler of the output. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
 ---------------------
 
 .. function:: proc_handler_t *obs_output_get_proc_handler(const obs_output_t *output)
 
-   :return: The procedure handler of the output
+   :return: The procedure handler of the output. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
 ---------------------
 

docs/sphinx/reference-properties.rst

@@ -649,36 +649,60 @@ Property Modification Functions
 
    Adds a string to a string list.
 
+   :param    name: Localized name shown to user
+   :param    val:  The actual string value stored and will be returned by :c:func:`obs_data_get_string`
+   :returns: The index of the list item.
+
 ---------------------
 
 .. function:: size_t obs_property_list_add_int(obs_property_t *p, const char *name, long long val)
 
    Adds an integer to a integer list.
 
+   :param    name: Localized name shown to user
+   :param    val:  The actual int value stored and will be returned by :c:func:`obs_data_get_int`
+   :returns: The index of the list item.
+
 ---------------------
 
 .. function:: size_t obs_property_list_add_float(obs_property_t *p, const char *name, double val)
 
    Adds a floating point to a floating point list.
 
+   :param    name: Localized name shown to user
+   :param    val:  The actual float value stored and will be returned by :c:func:`obs_data_get_double`
+   :returns: The index of the list item.
+
 ---------------------
 
 .. function:: void obs_property_list_insert_string(obs_property_t *p, size_t idx, const char *name, const char *val)
 
    Inserts a string in to a string list.
 
+   :param    idx:  The index of the list item
+   :param    name: Localized name shown to user
+   :param    val:  The actual string value stored and will be returned by :c:func:`obs_data_get_string`
+
 ---------------------
 
 .. function:: void obs_property_list_insert_int(obs_property_t *p, size_t idx, const char *name, long long val)
 
    Inserts an integer in to an integer list.
 
+   :param    idx:  The index of the list item
+   :param    name: Localized name shown to user
+   :param    val:  The actual int value stored and will be returned by :c:func:`obs_data_get_int`
+
 ---------------------
 
 .. function:: void obs_property_list_insert_float(obs_property_t *p, size_t idx, const char *name, double val)
 
    Inserts a floating point in to a floating point list.
 
+   :param    idx:  The index of the list item.
+   :param    name: Localized name shown to user
+   :param    val:  The actual float value stored and will be returned by :c:func:`obs_data_get_double`
+
 ---------------------
 
 .. function:: void obs_property_list_item_disable(obs_property_t *p, size_t idx, bool disabled)

docs/sphinx/reference-scenes.rst

@@ -208,7 +208,7 @@ General Scene Functions
 .. function:: obs_scene_t *obs_scene_get_ref(obs_scene_t *scene)
 
    Returns an incremented reference if still valid, otherwise returns
-   *NULL*.
+   *NULL*. Release with :c:func:`obs_scene_release()`.
 
 ---------------------
 
@@ -549,7 +549,8 @@ Scene Item Functions
 
    :return: An incremented reference to the private settings of the
             scene item.  Allows the front-end to set custom information
-            which is saved with the scene item
+            which is saved with the scene item. Release with
+            :c:func:`obs_data_release()`.
 
 ---------------------
 

docs/sphinx/reference-services.rst

@@ -200,7 +200,7 @@ General Service Functions
 .. function:: obs_service_t *obs_service_get_ref(obs_service_t *service)
 
    Returns an incremented reference if still valid, otherwise returns
-   *NULL*.
+   *NULL*. Release with :c:func:`obs_service_release()`.
 
 ---------------------
 
@@ -236,7 +236,8 @@ General Service Functions
 
 .. function:: obs_data_t *obs_service_defaults(const char *id)
 
-   :return: An incremented reference to the service's default settings
+   :return: An incremented reference to the service's default settings.
+            Release with :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -254,7 +255,8 @@ General Service Functions
 
 .. function:: obs_data_t *obs_service_get_settings(const obs_service_t *service)
 
-   :return: An incremented reference to the service's settings
+   :return: An incremented reference to the service's settings. Release with
+            :c:func:`obs_data_release()`.
 
 ---------------------
 

docs/sphinx/reference-settings.rst

@@ -25,7 +25,8 @@ General Functions
 
 .. function:: obs_data_t *obs_data_create()
 
-   :return: A new reference to a data object.
+   :return: A new reference to a data object. Release with
+            :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -34,7 +35,8 @@ General Functions
    Creates a data object from a Json string.
 
    :param json_string: Json string
-   :return:            A new reference to a data object
+   :return:            A new reference to a data object. Release with
+                       :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -43,7 +45,8 @@ General Functions
    Creates a data object from a Json file.
 
    :param json_file: Json file path
-   :return:          A new reference to a data object
+   :return:          A new reference to a data object. Release with
+                     :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -54,7 +57,8 @@ General Functions
 
    :param json_file:  Json file path
    :param backup_ext: Backup file extension
-   :return:           A new reference to a data object
+   :return:           A new reference to a data object. Release with
+                       :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -176,13 +180,15 @@ Get Functions
 
 .. function:: obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name)
 
-   :return: An incremented reference to a data object.
+   :return: An incremented reference to a data object. Release with
+            :c:func:`obs_data_release()`.
 
 ---------------------
 
 .. function:: obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name)
 
-   :return: An incremented reference to a data array object.
+   :return: An incremented reference to a data array object. Release
+            with :c:func:`obs_data_array_release()`.
 
 ---------------------
 
@@ -224,7 +230,8 @@ is not set.
 .. function:: void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj)
               obs_data_t *obs_data_get_default_obj(obs_data_t *data, const char *name)
 
-   :return: An incremented reference to a data object.
+   :return: An incremented reference to a data object. Release with
+            :c:func:`obs_data_release()`.
 
 ----------------------
 
@@ -262,7 +269,8 @@ inappropriate or invalid.
 .. function:: void obs_data_set_autoselect_obj(obs_data_t *data, const char *name, obs_data_t *obj)
               obs_data_t *obs_data_get_autoselect_obj(obs_data_t *data, const char *name)
 
-   :return: An incremented reference to a data object.
+   :return: An incremented reference to a data object. Release with
+            :c:func:`obs_data_release()`.
 
 ---------------------
 
@@ -272,7 +280,8 @@ Array Functions
 
 .. function:: obs_data_array_t *obs_data_array_create()
 
-   :return: A new reference to a data array object.
+   :return: A new reference to a data array object. Release
+            with :c:func:`obs_data_array_release()`.
 
 ---------------------
 
@@ -291,7 +300,7 @@ Array Functions
 .. function:: obs_data_t *obs_data_array_item(obs_data_array_t *array, size_t idx)
 
    :return: An incremented reference to the data object associated with
-            this array entry.
+            this array entry. Release with :c:func:`obs_data_release()`.
 
 ---------------------
 

docs/sphinx/reference-sources.rst

@@ -692,7 +692,7 @@ General Source Functions
    Creates a source of the specified type with the specified settings.
 
    The "source" context is used for anything related to presenting
-   or modifying video/audio.  Use obs_source_release to release it.
+   or modifying video/audio.  Use :c:func:`obs_source_release` to release it.
 
    :param   id:             The source type string identifier
    :param   name:           The desired name of the source.  If this is
@@ -732,7 +732,8 @@ General Source Functions
 
    Duplicates a source.  If the source has the
    OBS_SOURCE_DO_NOT_DUPLICATE output flag set, this only returns a
-   new reference to the same source.
+   new reference to the same source. Either way,
+   release with :c:func:`obs_source_release`.
 
    :param source:         The source to duplicate
    :param desired_name:   The desired name of the new source.  If this is
@@ -756,7 +757,7 @@ General Source Functions
 .. function:: obs_source_t *obs_source_get_ref(obs_source_t *source)
 
    Returns an incremented reference if still valid, otherwise returns
-   *NULL*.
+   *NULL*. Use :c:func:`obs_source_release` to release it.
 
 ---------------------
 
@@ -945,7 +946,8 @@ General Source Functions
 
 .. function:: signal_handler_t *obs_source_get_signal_handler(const obs_source_t *source)
 
-   :return: The source's signal handler
+   :return: The source's signal handler. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
    See the :ref:`source_signal_handler_reference` for more information
    on signals that are available for sources.
@@ -954,7 +956,8 @@ General Source Functions
 
 .. function:: proc_handler_t *obs_source_get_proc_handler(const obs_source_t *source)
 
-   :return: The procedure handler for a source
+   :return: The procedure handler for a source. Should not be manually freed,
+            as its lifecycle is managed by libobs.
 
 ---------------------
 
@@ -995,7 +998,7 @@ General Source Functions
 .. function:: void obs_source_set_audio_mixers(obs_source_t *source, uint32_t mixers)
               uint32_t obs_source_get_audio_mixers(const obs_source_t *source)
 
-   Sets/gets the audio mixer channels that a source outputs to,
+   Sets/gets the audio mixer channels (i.e. audio tracks) that a source outputs to,
    depending on what bits are set.  Audio mixers allow filtering
    specific using multiple audio encoders to mix different sources
    together depending on what mixer channel they're set to.
@@ -1182,7 +1185,8 @@ General Source Functions
 .. function:: obs_data_t *obs_source_get_private_settings(obs_source_t *item)
 
    Gets private front-end settings data.  This data is saved/loaded
-   automatically.  Returns an incremented reference.
+   automatically.  Returns an incremented reference. Use :c:func:`obs_data_release()`
+   to release it.
 
 ---------------------
 
@@ -1493,7 +1497,8 @@ Transitions
    :param target: | OBS_TRANSITION_SOURCE_A - Source being transitioned from, or the current source if not transitioning
                   | OBS_TRANSITION_SOURCE_B - Source being transitioned to
    :return:       An incremented reference to the source or destination
-                  sources of the transition
+                  sources of the transition. Use :c:func:`obs_source_release`
+                  to release it.
 
 ---------------------
 
@@ -1506,7 +1511,7 @@ Transitions
 .. function:: obs_source_t *obs_transition_get_active_source(obs_source_t *transition)
 
    :return: An incremented reference to the currently active source of
-            the transition
+            the transition. Use :c:func:`obs_source_release` to release it.
 
 ---------------------