[nautilus/antoniof/someloveforeel: 2/4] eel-string: Fix API comment

[António Fernandes <antoniof src gnome org>]

commit f2f094762764f5bb3ba4481f4ccb5888214a12eb
Author: António Fernandes <antoniof gnome org>
Date:   Tue Feb 6 17:45:36 2018 +0000

    eel-string: Fix API comment
    
    eel_string_ellispize_*() functions and eel-gdk-extension.h
    are no more. This comment was totally outdated.
    
    Replace it with actual API docs.

 eel/eel-string.c | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
---
diff --git a/eel/eel-string.c b/eel/eel-string.c
index a4cdfc31d..df1209919 100644
--- a/eel/eel-string.c
+++ b/eel/eel-string.c
@@ -89,14 +89,21 @@ eel_str_capitalize (const char *string)
     return capitalized;
 }
 
-/* Note: eel_string_ellipsize_* that use a length in pixels
- * rather than characters can be found in eel_gdk_extensions.h
+/**
+ * eel_str_middle_truncate:
+ * @string: the original string
+ * @truncate_length: the number of characters of the truncated string (min. 3).
  *
- * FIXME bugzilla.eazel.com 5089:
- * we should coordinate the names of eel_string_ellipsize_*
- * and eel_str_*_truncate so that they match better and reflect
- * their different behavior.
- */
+ * Replaces a number of characters in the middle of a @string with an ellipsis
+ * character, to obtain a number of characters equal to @truncate_length, if the
+ * original @string is longer than that.
+ *
+ * Useful to ellipsise a variable substring (such as a file name) with variable
+ * lengh. Do not use this for full labels, use PangoLayout instead.
+ *
+ * Returns: (transfer full): a newly allocated truncated string, or a copy of
+ * @string if it was not longer than @truncate_length.
+ **/
 char *
 eel_str_middle_truncate (const char *string,
                          guint       truncate_length)