clean up the documentation (#22196)

12 files changed, 28 insertions, 34 deletions

diff --git a/compiler/readme.md b/compiler/readme.md
index ac47508dc..4a197991c 100644
--- a/compiler/readme.md
+++ b/compiler/readme.md
@@ -4,4 +4,4 @@
 - Note that this code has been translated from a bootstrapping version written in Pascal.
 - So the code is **not** a poster child of good Nim code.
 
-See [Internals of the Nim Compiler](https://nim-lang.org/docs/intern.html) for more information.
+See [Internals of the Nim Compiler](https://nim-lang.github.io/Nim/intern.html) for more information.
diff --git a/doc/advopt.txt b/doc/advopt.txt
index 8362bbf4c..e4d11081a 100644
--- a/doc/advopt.txt
+++ b/doc/advopt.txt
@@ -48,7 +48,7 @@ Advanced options:
   --unitsep:on|off          use the ASCII unit separator (31) between error
                             messages, useful for IDE-like tooling
   --declaredLocs:on|off     show declaration locations in messages
-  --spellSuggest|:num       show at most `num >= 0` spelling suggestions on typos.
+  --spellSuggest:num        show at most `num >= 0` spelling suggestions on typos.
                             if `num` is not specified (or `auto`), return
                             an implementation defined set of suggestions.
   --hints:on|off|list.      `on|off` enables or disables hints.
diff --git a/doc/filelist.txt b/doc/filelist.txt
index 74995f154..5522414fe 100644
--- a/doc/filelist.txt
+++ b/doc/filelist.txt
@@ -31,16 +31,14 @@ semstmts        contains the semantic checking phase for statements
 semtypes        contains the semantic checking phase for types
 seminst         instantiation of generic procs and types
 semfold         contains code to deal with constant folding
-semthreads      deep program analysis for threads
-evals           contains an AST interpreter for compile time evaluation
+sempass2        Second semantic checking pass over the AST
+vm              contains an AST interpreter for compile time evaluation
 pragmas         semantic checking of pragmas
 
 idents          implements a general mapping from identifiers to an internal
                 representation (`PIdent`) that is used so that a simple
                 id-comparison suffices to establish whether two Nim
                 identifiers are equivalent
-ropes           implements long strings represented as trees for
-                lazy evaluation; used mainly by the code generators
 
 transf          transformations on the AST that need to be done before
                 code generation
diff --git a/doc/manual.md b/doc/manual.md
index aa53c4512..1c3e66879 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -2978,9 +2978,9 @@ ref or pointer type             nil
 procedural type                 nil
 sequence                        `@[]`
 string                          `""`
-`tuple[x: A, y: B, ...]`        (default(A), default(B), ...)
+`tuple[x: A, y: B, ...]`        (zeroDefault(A), zeroDefault(B), ...)
                                 (analogous for objects)
-`array[0..., T]`                `[default(T), ...]`
+`array[0..., T]`                `[zeroDefault(T), ...]`
 `range[T]`                      default(T); this may be out of the valid range
 T = enum                        `cast[T](0)`; this may be an invalid value
 ============================    ==============================================
@@ -8735,9 +8735,7 @@ model low level lockfree mechanisms:
 
 
 The `locks` pragma takes a list of lock expressions `locks: [a, b, ...]`
-in order to support *multi lock* statements. Why these are essential is
-explained in the [lock levels](manual_experimental.md#lock-levels) section
-of the experimental manual.
+in order to support *multi lock* statements.
 
 
 ### Protecting general locations
diff --git a/doc/mm.md b/doc/mm.md
index 9d1fc1955..431517b17 100644
--- a/doc/mm.md
+++ b/doc/mm.md
@@ -38,7 +38,7 @@ instead entire subgraphs are *moved* between threads. The Nim compiler also aggr
 optimizes away RC ops and exploits [move semantics](destructors.html#move-semantics).
 
 Nim performs a fair share of optimizations for ARC/ORC; you can inspect what it did
-to your time critical function via `--expandArc:functionName`.
+to your time critical function via `--expandArc:functionName`. Likewise, you can inspect the whole module via `--expandArc:fileName`.
 
 `--mm:arc` uses the same mechanism as `--mm:orc`, but it leaves out the cycle collector.
 Both ARC and ORC offer deterministic performance for `hard realtime`:idx: systems, but
diff --git a/doc/nims.md b/doc/nims.md
index 2409bb577..01cdf47c3 100644
--- a/doc/nims.md
+++ b/doc/nims.md
@@ -329,7 +329,7 @@ Evolving Scripting language
 
 NimScript evolves together with Nim,
 [occasionally new features might become available on NimScript](
-https://github.com/nim-lang/Nim/pulls?utf8=%E2%9C%93&q=nimscript),
+https://github.com/nim-lang/Nim/pulls?q=nimscript+is%3Amerged),
 adapted from compiled Nim or added as new features on both.
 
 Scripting Language with a Package Manager
diff --git a/doc/nimsuggest.md b/doc/nimsuggest.md
index 97cb2b1fa..3d076a6f5 100644
--- a/doc/nimsuggest.md
+++ b/doc/nimsuggest.md
@@ -49,7 +49,7 @@ via sockets is more reasonable so that is the default. It listens to port 6000
 by default.
 
 Nimsuggest is basically a frontend for the nim compiler so `--path`:option: flags and
-[config files](https://nim-lang.org/docs/nimc.html#compiler-usage-configuration-files)
+[config files](nimc.html#compiler-usage-configuration-files)
 can be used to specify additional dependencies like 
 `nimsuggest --stdin --debug --path:"dependencies" myproject.nim`:cmd:.
 
diff --git a/doc/readme.txt b/doc/readme.txt
index 7b1a445b5..1157752b9 100644
--- a/doc/readme.txt
+++ b/doc/readme.txt
@@ -3,5 +3,5 @@ Nim's documentation system
 ============================
 
 This folder contains Nim's documentation. The documentation
-is written in a format called *reStructuredText*, a markup language that reads
+is written in a format called *Markdown*, a markup language that reads
 like ASCII and can be converted to HTML automatically!
diff --git a/doc/sets_fragment.txt b/doc/sets_fragment.txt
index 6e0991a9e..35b1fc023 100644
--- a/doc/sets_fragment.txt
+++ b/doc/sets_fragment.txt
@@ -17,15 +17,13 @@ The reason is that sets are implemented as high performance bit vectors.
 Attempting to declare a set with a larger type will result in an error:
 
 ```nim
-
   var s: set[int64] # Error: set is too large; use `std/sets` for ordinal types
                     # with more than 2^16 elements
-
 ```
 
 
 **Note:** Nim also offers [hash sets](sets.html) (which you need to import
-with `import sets`), which have no such restrictions.
+with `import std/sets`), which have no such restrictions.
 
 Sets can be constructed via the set constructor: `{}` is the empty set. The
 empty set is type compatible with any concrete set type. The constructor
@@ -41,7 +39,7 @@ can also be used to include elements (and ranges of elements):
                            # from '0' to '9'
   ```
 
-The module [`std/setutils`](https://nim-lang.org/docs/setutils.html) provides a way to initialize a set from an iterable:
+The module [`std/setutils`](setutils.html) provides a way to initialize a set from an iterable:
 
 ```nim
 import std/setutils
diff --git a/doc/tools.md b/doc/tools.md
index 3eda60b13..baf7ce386 100644
--- a/doc/tools.md
+++ b/doc/tools.md
@@ -37,7 +37,7 @@ The standard distribution ships with the following tools:
   | `nimpretty`:cmd: is a Nim source code beautifier,
     to format code according to the official style guide.
 
-- | [testament](https://nim-lang.github.io/Nim/testament.html)
+- | [testament](testament.html)
   | `testament`:cmd: is an advanced automatic *unittests runner* for Nim tests,
     is used for the development of Nim itself, offers process isolation for your tests,
     it can generate statistics about test cases, supports multiple targets (C, JS, etc),
diff --git a/doc/tut3.md b/doc/tut3.md
index ccb2eb809..67f49c879 100644
--- a/doc/tut3.md
+++ b/doc/tut3.md
@@ -366,7 +366,7 @@ recommended way. But still `strformat` is a good example for a
 practical use case for a macro that is slightly more complex than the
 `assert` macro.
 
-[Strformat](https://github.com/nim-lang/Nim/blob/5845716df8c96157a047c2bd6bcdd795a7a2b9b1/lib/pure/strformat.nim#L280)
+[Strformat](https://github.com/nim-lang/Nim/blob/devel/lib/pure/strformat.nim)
 
 Ast Pattern Matching
 --------------------
diff --git a/lib/system.nim b/lib/system.nim
index 845ab58e6..94e897b2b 100644
--- a/lib/system.nim
+++ b/lib/system.nim
@@ -25,7 +25,11 @@
 include "system/basic_types"
 
 func zeroDefault*[T](_: typedesc[T]): T {.magic: "ZeroDefault".} =
-  ## returns the default value of the type `T`.
+  ## Returns the binary zeros representation of the type `T`. It ignores
+  ## default fields of an object.
+  ##
+  ## See also:
+  ## * `default <#default,typedesc[T]>`_
 
 include "system/compilation"
 
@@ -916,22 +920,18 @@ proc `@`* [IDX, T](a: sink array[IDX, T]): seq[T] {.magic: "ArrToSeq", noSideEff
   ##   ```
 
 proc default*[T](_: typedesc[T]): T {.magic: "Default", noSideEffect.} =
-  ## returns the default value of the type `T`.
+  ## Returns the default value of the type `T`. Contrary to `zeroDefault`, it takes default fields
+  ## of an object into consideration.
+  ##
+  ## See also:
+  ## * `zeroDefault <#zeroDefault,typedesc[T]>`_
+  ##
   runnableExamples:
     assert (int, float).default == (0, 0.0)
-    # note: `var a = default(T)` is usually the same as `var a: T` and (currently) generates
-    # a value whose binary representation is all 0, regardless of whether this
-    # would violate type constraints such as `range`, `not nil`, etc. This
-    # property is required to implement certain algorithms efficiently which
-    # may require intermediate invalid states.
     type Foo = object
       a: range[2..6]
-    var a1: range[2..6] # currently, this compiles
-    # var a2: Foo # currently, this errors: Error: The Foo type doesn't have a default value.
-    # var a3 = Foo() # ditto
-    var a3 = Foo.default # this works, but generates a `UnsafeDefault` warning.
-  # note: the doc comment also explains why `default` can't be implemented
-  # via: `template default*[T](t: typedesc[T]): T = (var v: T; v)`
+    var x = Foo.default
+    assert x.a == 2
 
 
 proc reset*[T](obj: var T) {.noSideEffect.} =