[tepl/wip/utils-public: 1/2] Utils: make str_middle_truncate() public

[Sébastien Wilmet <swilmet src gnome org>]

commit dbf38e87ffefb167a44044d9eb5aeb614b8c133d
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Mon Nov 4 12:49:24 2019 +0100

    Utils: make str_middle_truncate() public
    
    It will be used by gedit.

 docs/reference/tepl-4.0-sections.txt |  5 +++++
 docs/reference/tepl-docs.xml.in      |  1 +
 tepl/tepl-tab-label.c                |  2 +-
 tepl/tepl-utils.c                    | 23 ++++++++++++++++++-----
 tepl/tepl-utils.h                    |  3 +--
 5 files changed, 26 insertions(+), 8 deletions(-)
---
diff --git a/docs/reference/tepl-4.0-sections.txt b/docs/reference/tepl-4.0-sections.txt
index a9f7898..a5ec35f 100644
--- a/docs/reference/tepl-4.0-sections.txt
+++ b/docs/reference/tepl-4.0-sections.txt
@@ -385,6 +385,11 @@ TeplNotebookPrivate
 tepl_notebook_get_type
 </SECTION>
 
+<SECTION>
+<FILE>utils</FILE>
+tepl_utils_str_middle_truncate
+</SECTION>
+
 <SECTION>
 <FILE>view</FILE>
 TeplView
diff --git a/docs/reference/tepl-docs.xml.in b/docs/reference/tepl-docs.xml.in
index 68e835a..0a22194 100644
--- a/docs/reference/tepl-docs.xml.in
+++ b/docs/reference/tepl-docs.xml.in
@@ -61,6 +61,7 @@
       <xi:include href="xml/abstract-factory-vala.xml"/>
       <xi:include href="xml/info-bar.xml"/>
       <xi:include href="xml/iter.xml"/>
+      <xi:include href="xml/utils.xml"/>
     </chapter>
   </part>
 
diff --git a/tepl/tepl-tab-label.c b/tepl/tepl-tab-label.c
index b8d5f07..e625406 100644
--- a/tepl/tepl-tab-label.c
+++ b/tepl/tepl-tab-label.c
@@ -82,7 +82,7 @@ update_label (TeplTabLabel *tab_label)
        /* A GtkNotebook tab label doesn't support well an ellipsizing GtkLabel.
         * So, ellipsize ourself.
         */
-       truncated_short_title = _tepl_utils_str_middle_truncate (short_title, MAX_LABEL_CHARS_LENGTH);
+       truncated_short_title = tepl_utils_str_middle_truncate (short_title, MAX_LABEL_CHARS_LENGTH);
 
        gtk_label_set_text (tab_label->priv->label, truncated_short_title);
 
diff --git a/tepl/tepl-utils.c b/tepl/tepl-utils.c
index 5652b4d..401b3ee 100644
--- a/tepl/tepl-utils.c
+++ b/tepl/tepl-utils.c
@@ -26,10 +26,10 @@
 #include <string.h>
 #include "tepl-application-window.h"
 
-/*
+/**
  * SECTION:utils
- * @title: TeplUtils
- * @short_description: Utility functions
+ * @Short_description: Utility functions
+ * @Title: TeplUtils
  *
  * Utility functions.
  */
@@ -93,9 +93,22 @@ str_truncate (const gchar *string,
        return g_string_free (truncated, FALSE);
 }
 
+/**
+ * tepl_utils_str_middle_truncate:
+ * @str: a UTF-8 string.
+ * @truncate_length: maximum length allowed for @str, in UTF-8 characters (not
+ *   bytes).
+ *
+ * If @str is longer than @truncate_length, then this function returns @str
+ * truncated in the middle with a “…” character. Otherwise it just returns a
+ * copy of @str.
+ *
+ * Returns: the truncated string. Free with g_free().
+ * Since: 4.4
+ */
 gchar *
-_tepl_utils_str_middle_truncate (const gchar *str,
-                                guint        truncate_length)
+tepl_utils_str_middle_truncate (const gchar *str,
+                               guint        truncate_length)
 {
        return str_truncate (str, truncate_length, TRUE);
 }
diff --git a/tepl/tepl-utils.h b/tepl/tepl-utils.h
index f1fd40b..9fbe09a 100644
--- a/tepl/tepl-utils.h
+++ b/tepl/tepl-utils.h
@@ -30,8 +30,7 @@ G_BEGIN_DECLS
 
 /* String utilities */
 
-G_GNUC_INTERNAL
-gchar *                _tepl_utils_str_middle_truncate                 (const gchar *str,
+gchar *                tepl_utils_str_middle_truncate                  (const gchar *str,
                                                                 guint        truncate_length);
 
 /* File utilities */