Merge pull request #2946 from SethBarberee/gears_string_doc

gears.string doc revamp

lib/gears/string.lua

@@ -11,7 +11,7 @@ local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;",
 --- Escape a string from XML char.
 -- Useful to set raw text in textbox.
 -- @param text Text to escape.
--- @return Escape text.
+-- @treturn string Escaped text.
 -- @staticfct gears.string.xml_escape
 function gstring.xml_escape(text)
     return text and text:gsub("['&<>\"]", xml_entity_names) or nil
@@ -22,13 +22,14 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "
 
 --- Unescape a string from entities.
 -- @param text Text to unescape.
--- @return Unescaped text.
+-- @treturn string Unescaped text.
 -- @staticfct gears.string.xml_unescape
 function gstring.xml_unescape(text)
     return text and text:gsub("&(%a+);", xml_entity_chars) or nil
 end
 
---- Count number of lines in a string
+--- Count number of lines in a string.
+-- @DOC_text_gears_string_linecount_EXAMPLE@
 -- @tparam string text Input string.
 -- @treturn int Number of lines.
 -- @staticfct gears.string.linecount
@@ -37,10 +38,11 @@ function gstring.linecount(text)
 end
 
 --- Split a string into multiple lines.
--- @param text String to wrap.
--- @param width Maximum length of each line. Default: 72.
--- @param indent Number of spaces added before each wrapped line. Default: 0.
--- @return The string with lines wrapped to width.
+-- @DOC_text_gears_string_linewrap_EXAMPLE@
+-- @tparam string text String to wrap.
+-- @tparam number width Maximum length of each line. Default: 72.
+-- @tparam number indent Number of spaces added before each wrapped line. Default: 0.
+-- @treturn string The string with lines wrapped to width.
 -- @staticfct gears.string.linewrap
 function gstring.linewrap(text, width, indent)
     text = text or ""
@@ -60,6 +62,9 @@ end
 --- Escape all special pattern-matching characters so that lua interprets them
 -- literally instead of as a character class.
 -- Source: http://stackoverflow.com/a/20778724/15690
+-- @DOC_text_gears_string_quote_pattern_EXAMPLE@
+-- @tparam string s String to generate pattern for
+-- @treturn string string with escaped characters
 -- @staticfct gears.string.quote_pattern
 function gstring.quote_pattern(s)
     -- All special characters escaped in a string: %%, %^, %$, ...
@@ -68,7 +73,7 @@ function gstring.quote_pattern(s)
 end
 
 --- Generate a pattern matching expression that ignores case.
--- @param s Original pattern matching expression.
+-- @tparam string q Original pattern matching expression.
 -- @staticfct gears.string.query_to_pattern
 function gstring.query_to_pattern(q)
     local s = gstring.quote_pattern(q)
@@ -102,7 +107,9 @@ function gstring.split(str, delimiter)
 end
 
 --- Check if a string starts with another string.
+-- @DOC_text_gears_string_startswith_EXAMPLE@
 -- @tparam string str String to search
+-- @treturn boolean `true` if string starts with specified string
 -- @tparam string sub String to check for.
 -- @staticfct gears.string.startswith
 function gstring.startswith(str, sub)
@@ -110,8 +117,10 @@ function gstring.startswith(str, sub)
 end
 
 --- Check if a string ends with another string.
+-- @DOC_text_gears_string_endswith_EXAMPLE@
 -- @tparam string str String to search
 -- @tparam string sub String to check for.
+-- @treturn boolean `true` if string ends with specified string
 -- @staticfct gears.string.endswith
 function gstring.endswith(str, sub)
     return sub == "" or string.sub(str,-string.len(sub)) == sub

tests/examples/text/gears/string/endswith.lua

@@ -0,0 +1,12 @@
+--DOC_GEN_OUTPUT --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local test = "do.it"
+local res = gears.string.endswith(test,"it")
+print(tostring(res))
+assert(res == true) --DOC_HIDE
+
+res = gears.string.endswith(test,"do")
+print(tostring(res))
+assert(res == false) --DOC_HIDE
+

tests/examples/text/gears/string/endswith.output.txt

@@ -0,0 +1,2 @@
+true
+false

tests/examples/text/gears/string/linecount.lua

@@ -0,0 +1,11 @@
+--DOC_GEN_OUTPUT --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local test = "do.t"
+local res = gears.string.linecount(test)
+print("Count is: " .. res)
+
+local test2 = "do\nit\nnow"
+local res2 = gears.string.linecount(test2)
+print("Count is: " .. res2)
+

tests/examples/text/gears/string/linecount.output.txt

@@ -0,0 +1,2 @@
+Count is: 1
+Count is: 3

tests/examples/text/gears/string/linewrap.lua

@@ -0,0 +1,6 @@
+--DOC_GEN_OUTPUT --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local test = "do it"
+local res = gears.string.linewrap(test, 2, 0)
+print(res)

tests/examples/text/gears/string/linewrap.output.txt

@@ -0,0 +1,2 @@
+do
+it

tests/examples/text/gears/string/quote_pattern.lua

@@ -0,0 +1,6 @@
+--DOC_GEN_OUTPUT --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local test = "do.it"
+local res = gears.string.quote_pattern(test)
+print(res)

tests/examples/text/gears/string/quote_pattern.output.txt

@@ -0,0 +1 @@
+do%.it

tests/examples/text/gears/string/startswith.lua

@@ -0,0 +1,11 @@
+--DOC_GEN_OUTPUT --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local test = "do.it"
+local res = gears.string.startswith(test,"do")
+print(tostring(res)) -- Print boolean value
+assert(res == true) --DOC_HIDE
+
+res = gears.string.startswith(test,"it")
+print(tostring(res)) -- print boolean value
+assert(res == false) --DOC_HIDE

tests/examples/text/gears/string/startswith.output.txt

@@ -0,0 +1,2 @@
+true
+false