From abb2da99a889b57c92bee6d4231184dc9a3474b9 Mon Sep 17 00:00:00 2001
From: CodeYan01 <65320293+CodeYan01@users.noreply.github.com>
Date: Fri, 21 Jul 2023 11:20:00 +0800
Subject: [PATCH] docs: Clarify strlist_split

---
 docs/sphinx/reference-libobs-util-dstr.rst | 27 ++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/sphinx/reference-libobs-util-dstr.rst b/docs/sphinx/reference-libobs-util-dstr.rst
index 92951495f..91794e2d6 100644
--- a/docs/sphinx/reference-libobs-util-dstr.rst
+++ b/docs/sphinx/reference-libobs-util-dstr.rst
@@ -87,8 +87,31 @@ General String Helper Functions
 
 .. function:: char **strlist_split(const char *str, char split_ch, bool include_empty)
 
-   Splits a string in to a list of multiple sub-strings.  Free with
-   :c:func:`strlist_free()`.
+   Splits a string in to a list of multiple sub-strings, terminated by
+   ``NULL``. If ``split_ch`` does not exist in the string, the first
+   sub-string will be the same as ``str``. Free with :c:func:`strlist_free()`.
+
+   :param str: The string to be split
+   :param split_ch: The delimiter
+   :param include_empty: If *true*, empty strings caused by having the
+                         ``split_ch`` right next to another will be
+                         included in the list. If *false*, they won't
+                         be included.
+
+   Sample usage:
+
+   .. code:: cpp
+
+      char **words = strlist_split("OBS    Studio", ' ', false);
+      int count = 0;
+
+      for (char **word = words; *word; ++word) {
+              count++;
+              blog(LOG_DEBUG, "%s", *word);
+      }
+
+      strlist_free(words);
+      // count == 2
 
 ----------------------