follow up #16399 clean up docs (#16539)

* follow up #16399 clean up docs

* more

lib/pure/cstrutils.nim

@@ -7,8 +7,8 @@
 #    distribution, for details about the copyright.
 #
 
-## This module supports helper routines for working with ``cstring``
+## This module supports helper routines for working with `cstring`
-## without having to convert ``cstring`` to ``string`` in order to
+## without having to convert `cstring` to `string` in order to
 ## save allocations.
 
 include "system/inclrtl"
@@ -16,41 +16,45 @@ import std/private/strimpl
 
 
 when defined(js):
-  proc startsWith*(s, prefix: cstring): bool {.noSideEffect,
+  func startsWith*(s, prefix: cstring): bool {.importjs: "#.startsWith(#)".}
-    importjs: "#.startsWith(#)".}
 
-  proc endsWith*(s, suffix: cstring): bool {.noSideEffect,
+  func endsWith*(s, suffix: cstring): bool {.importjs: "#.endsWith(#)".}
-    importjs: "#.endsWith(#)".}
 
-  proc cmpIgnoreStyle*(a, b: cstring): int {.noSideEffect.} =
+  func cmpIgnoreStyle*(a, b: cstring): int =
     cmpIgnoreStyleImpl(a, b)
 
-  proc cmpIgnoreCase*(a, b: cstring): int {.noSideEffect.} =
+  func cmpIgnoreCase*(a, b: cstring): int =
     cmpIgnoreCaseImpl(a, b)
 
   # JS string has more operations that might warrant its own module:
   # https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
 else:
-  proc startsWith*(s, prefix: cstring): bool {.noSideEffect,
+  func startsWith*(s, prefix: cstring): bool {.rtl, extern: "csuStartsWith".} =
-    rtl, extern: "csuStartsWith".} =
+    ## Returns true if `s` starts with `prefix`.
-    ## Returns true if ``s`` starts with ``prefix``.
     ##
-    ## If ``prefix == ""`` true is returned.
+    ## If `prefix == ""` true is returned.
     ## 
-    ## JS backend uses native ``String.prototype.startsWith``.
+    ## JS backend uses native `String.prototype.startsWith`.
+    runnableExamples:
+      assert startsWith(cstring"Hello, Nimion", cstring"Hello")
+      assert not startsWith(cstring"Hello, Nimion", cstring"Nimion")
+
     var i = 0
     while true:
       if prefix[i] == '\0': return true
       if s[i] != prefix[i]: return false
       inc(i)
 
-  proc endsWith*(s, suffix: cstring): bool {.noSideEffect,
+  func endsWith*(s, suffix: cstring): bool {.rtl, extern: "csuEndsWith".} =
-    rtl, extern: "csuEndsWith".} =
+    ## Returns true if `s` ends with `suffix`.
-    ## Returns true if ``s`` ends with ``suffix``.
     ##
-    ## If ``suffix == ""`` true is returned.
+    ## If `suffix == ""` true is returned.
     ##
-    ## JS backend uses native ``String.prototype.endsWith``.
+    ## JS backend uses native `String.prototype.endsWith`.
+    runnableExamples:
+      assert endsWith(cstring"Hello, Nimion", cstring"Nimion")
+      assert not endsWith(cstring"Hello, Nimion", cstring"Hello")
+
     let slen = s.len
     var i = 0
     var j = slen - len(suffix)
@@ -59,16 +63,18 @@ else:
       inc(i)
     if suffix[i] == '\0': return true
 
-  proc cmpIgnoreStyle*(a, b: cstring): int {.noSideEffect,
+  func cmpIgnoreStyle*(a, b: cstring): int {.rtl, extern: "csuCmpIgnoreStyle".} =
-    rtl, extern: "csuCmpIgnoreStyle".} =
+    ## Semantically the same as `cmp(normalize($a), normalize($b))`. It
-    ## Semantically the same as ``cmp(normalize($a), normalize($b))``. It
     ## is just optimized to not allocate temporary strings.  This should
     ## NOT be used to compare Nim identifier names. use `macros.eqIdent`
     ## for that. Returns:
     ##
-    ## | 0 if a == b
+    ## .. code-block::
-    ## | < 0 if a < b
+    ##   0 if a == b
-    ## | > 0 if a > b
+    ##   < 0 if a < b
+    ##   > 0 if a > b
+    runnableExamples:
+      assert cmpIgnoreStyle(cstring"hello", cstring"H_e_L_Lo") == 0
     var i = 0
     var j = 0
     while true:
@@ -81,13 +87,18 @@ else:
       inc(i)
       inc(j)
 
-  proc cmpIgnoreCase*(a, b: cstring): int {.noSideEffect,
+  func cmpIgnoreCase*(a, b: cstring): int {.rtl, extern: "csuCmpIgnoreCase".} =
-    rtl, extern: "csuCmpIgnoreCase".} =
     ## Compares two strings in a case insensitive manner. Returns:
     ##
-    ## | 0 if a == b
+    ## .. code-block::
-    ## | < 0 if a < b
+    ##   0 if a == b
-    ## | > 0 if a > b
+    ##   < 0 if a < b
+    ##   > 0 if a > b
+    runnableExamples:
+      assert cmpIgnoreCase(cstring"hello", cstring"HeLLo") == 0
+      assert cmpIgnoreCase(cstring"echo", cstring"hello") < 0
+      assert cmpIgnoreCase(cstring"yellow", cstring"hello") > 0
+
     var i = 0
     while true:
       var aa = toLowerAscii(a[i])