stdlib organization & documentation improvements (#20971)

* stdlib organization & documentation improvements

* fix CI

* Update doc/lib.md

Co-authored-by: Juan Carlos <juancarlospaco@gmail.com>

* fix ci, remove jshttpcore, export in jsfetch instead

* fix alphabetical order violations

* add cmdline, db_odbc

Co-authored-by: Juan Carlos <juancarlospaco@gmail.com>

15 files changed, 25 insertions, 87 deletions

diff --git a/lib/std/appdirs.nim b/lib/std/appdirs.nim
index 51e8fddac..e648fe0c1 100644
--- a/lib/std/appdirs.nim
+++ b/lib/std/appdirs.nim
@@ -1,3 +1,5 @@
+## This module implements helpers for determining special directories used by apps.
+
 from std/private/osappdirs import nil
 import std/paths
 import std/envvars
diff --git a/lib/std/decls.nim b/lib/std/decls.nim
index fc202522f..3f774cd08 100644
--- a/lib/std/decls.nim
+++ b/lib/std/decls.nim
@@ -1,5 +1,4 @@
-# see `semLowerLetVarCustomPragma` for compiler support that enables these
-# lowerings
+## This module implements syntax sugar for some declarations.
 
 import macros
 
diff --git a/lib/std/dirs.nim b/lib/std/dirs.nim
index adab9e9dd..df6107c51 100644
--- a/lib/std/dirs.nim
+++ b/lib/std/dirs.nim
@@ -1,3 +1,5 @@
+## This module implements directory handling.
+
 from paths import Path, ReadDirEffect, WriteDirEffect
 
 from std/private/osdirs import dirExists, createDir, existsOrCreateDir, removeDir,
diff --git a/lib/std/envvars.nim b/lib/std/envvars.nim
index d86f13f8d..46595a3cf 100644
--- a/lib/std/envvars.nim
+++ b/lib/std/envvars.nim
@@ -8,7 +8,7 @@
 #
 
 
-## The `std/envvars` module implements environment variables handling.
+## The `std/envvars` module implements environment variable handling.
 import std/oserrors
 
 type
diff --git a/lib/std/exitprocs.nim b/lib/std/exitprocs.nim
index c6537f7f8..d63c1abc5 100644
--- a/lib/std/exitprocs.nim
+++ b/lib/std/exitprocs.nim
@@ -7,6 +7,8 @@
 #    distribution, for details about the copyright.
 #
 
+## This module allows adding hooks to program exit.
+
 import locks
 
 type
diff --git a/lib/std/files.nim b/lib/std/files.nim
index 5bc7f7965..138bb5234 100644
--- a/lib/std/files.nim
+++ b/lib/std/files.nim
@@ -1,3 +1,5 @@
+## This module implements file handling.
+
 from paths import Path, ReadDirEffect, WriteDirEffect
 
 from std/private/osfiles import fileExists, removeFile,
diff --git a/lib/std/formatfloat.nim b/lib/std/formatfloat.nim
index 01b88d813..8abbe59cd 100644
--- a/lib/std/formatfloat.nim
+++ b/lib/std/formatfloat.nim
@@ -7,6 +7,8 @@
 #    distribution, for details about the copyright.
 #
 
+## This module implements formatting floats as strings.
+
 when defined(nimPreviewSlimSystem):
   import std/assertions
 else:
diff --git a/lib/std/genasts.nim b/lib/std/genasts.nim
index c5f51e5d9..05b2823ef 100644
--- a/lib/std/genasts.nim
+++ b/lib/std/genasts.nim
@@ -1,3 +1,5 @@
+## This module implements AST generation using captured variables for macros.
+
 import macros
 
 type GenAstOpt* = enum
diff --git a/lib/std/jsfetch.nim b/lib/std/jsfetch.nim
index 988414258..219594619 100644
--- a/lib/std/jsfetch.nim
+++ b/lib/std/jsfetch.nim
@@ -2,7 +2,8 @@
 when not defined(js):
   {.fatal: "Module jsfetch is designed to be used with the JavaScript backend.".}
 
-import std/[asyncjs, jsheaders, jsformdata]
+import std/[asyncjs, jsformdata, jsheaders]
+export jsformdata, jsheaders
 from std/httpcore import HttpMethod
 from std/jsffi import JsObject
 
@@ -116,7 +117,7 @@ func `$`*(self: Request | Response | FetchOptions): string = $toCstring(self)
 
 
 runnableExamples("-r:off"):
-  import std/[asyncjs, jsconsole, jsheaders, jsformdata]
+  import std/[asyncjs, jsconsole, jsformdata, jsheaders]
   from std/httpcore import HttpMethod
   from std/jsffi import JsObject
   from std/sugar import `=>`
diff --git a/lib/std/jsonutils.nim b/lib/std/jsonutils.nim
index 49367dac3..eec8dea7d 100644
--- a/lib/std/jsonutils.nim
+++ b/lib/std/jsonutils.nim
@@ -1,5 +1,5 @@
 ##[
-This module implements a hookable (de)serialization for arbitrary types.
+This module implements a hookable (de)serialization for arbitrary types using JSON.
 Design goal: avoid importing modules where a custom serialization is needed;
 see strtabs.fromJsonHook,toJsonHook for an example.
 ]##
diff --git a/lib/std/objectdollar.nim b/lib/std/objectdollar.nim
index f413bbc46..86ce9afc8 100644
--- a/lib/std/objectdollar.nim
+++ b/lib/std/objectdollar.nim
@@ -1,3 +1,5 @@
+## This module implements a generic `$` operator to convert objects to strings.
+
 import std/private/miscdollars
 
 proc `$`*[T: object](x: T): string =
diff --git a/lib/std/paths.nim b/lib/std/paths.nim
index 59f7653c8..c29096982 100644
--- a/lib/std/paths.nim
+++ b/lib/std/paths.nim
@@ -1,3 +1,5 @@
+## This module implements path handling.
+
 import std/private/osseps
 export osseps
 
diff --git a/lib/std/sums.nim b/lib/std/sums.nim
deleted file mode 100644
index a6ce1b85d..000000000
--- a/lib/std/sums.nim
+++ /dev/null
@@ -1,80 +0,0 @@
-#
-#
-#            Nim's Runtime Library
-#        (c) Copyright 2019 b3liever
-#
-#    See the file "copying.txt", included in this
-#    distribution, for details about the copyright.
-
-## Accurate summation functions.
-
-{.deprecated: "use the nimble package `sums` instead.".}
-
-runnableExamples:
-  import std/math
-
-  template `~=`(x, y: float): bool = abs(x - y) < 1e-4
-
-  let
-    n = 1_000_000
-    first = 1e10
-    small = 0.1
-  var data = @[first]
-  for _ in 1 .. n:
-    data.add(small)
-
-  let result = first + small * n.float
-
-  doAssert abs(sum(data) - result) > 0.3
-  doAssert sumKbn(data) ~= result
-  doAssert sumPairs(data) ~= result
-
-## See also
-## ========
-## * `math module <math.html>`_ for a standard `sum proc <math.html#sum,openArray[T]>`_
-
-func sumKbn*[T](x: openArray[T]): T =
-  ## Kahan-Babuška-Neumaier summation: O(1) error growth, at the expense
-  ## of a considerable increase in computational cost.
-  ##
-  ## See:
-  ## * https://en.wikipedia.org/wiki/Kahan_summation_algorithm#Further_enhancements
-  if len(x) == 0: return
-  var sum = x[0]
-  var c = T(0)
-  for i in 1 ..< len(x):
-    let xi = x[i]
-    let t = sum + xi
-    if abs(sum) >= abs(xi):
-      c += (sum - t) + xi
-    else:
-      c += (xi - t) + sum
-    sum = t
-  result = sum + c
-
-func sumPairwise[T](x: openArray[T], i0, n: int): T =
-  if n < 128:
-    result = x[i0]
-    for i in i0 + 1 ..< i0 + n:
-      result += x[i]
-  else:
-    let n2 = n div 2
-    result = sumPairwise(x, i0, n2) + sumPairwise(x, i0 + n2, n - n2)
-
-func sumPairs*[T](x: openArray[T]): T =
-  ## Pairwise (cascade) summation of `x[i0:i0+n-1]`, with O(log n) error growth
-  ## (vs O(n) for a simple loop) with negligible performance cost if
-  ## the base case is large enough.
-  ##
-  ## See, e.g.:
-  ## * https://en.wikipedia.org/wiki/Pairwise_summation
-  ## * Higham, Nicholas J. (1993), "The accuracy of floating point
-  ##   summation", SIAM Journal on Scientific Computing 14 (4): 783–799.
-  ##
-  ## In fact, the root-mean-square error growth, assuming random roundoff
-  ## errors, is only O(sqrt(log n)), which is nearly indistinguishable from O(1)
-  ## in practice. See:
-  ## * Manfred Tasche and Hansmartin Zeuner, Handbook of
-  ##   Analytic-Computational Methods in Applied Mathematics (2000).
-  let n = len(x)
-  if n == 0: T(0) else: sumPairwise(x, 0, n)
diff --git a/lib/std/symlinks.nim b/lib/std/symlinks.nim
index cb469d8c3..9e77bbe2a 100644
--- a/lib/std/symlinks.nim
+++ b/lib/std/symlinks.nim
@@ -1,3 +1,5 @@
+## This module implements symlink (symbolic link) handling.
+
 from paths import Path, ReadDirEffect
 
 from std/private/ossymlinks import symlinkExists, createSymlink, expandSymlink
diff --git a/lib/std/widestrs.nim b/lib/std/widestrs.nim
index f0f648c8d..8973579e1 100644
--- a/lib/std/widestrs.nim
+++ b/lib/std/widestrs.nim
@@ -7,7 +7,7 @@
 #    distribution, for details about the copyright.
 #
 
-# Nim support for C/C++'s `wide strings`:idx:.
+## Nim support for C/C++'s `wide strings`:idx:.
 
 #when not declared(ThisIsSystem):
 #  {.error: "You must not import this module explicitly".}