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>

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

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
 

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,

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

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

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,

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:

lib/std/genasts.nim

@@ -1,3 +1,5 @@
+## This module implements AST generation using captured variables for macros.
+
 import macros
 
 type GenAstOpt* = enum

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 `=>`

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.
 ]##

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 =

lib/std/paths.nim

@@ -1,3 +1,5 @@
+## This module implements path handling.
+
 import std/private/osseps
 export osseps
 

lib/std/sums.nim

@@ -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)

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

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".}