From 1ad618d96cab3f518b77c22432600e6b6bf56fae Mon Sep 17 00:00:00 2001 From: ringabout <43030857+ringabout@users.noreply.github.com> Date: Mon, 3 Jul 2023 04:36:05 +0800 Subject: [PATCH] clean up the documentation (#22196) --- compiler/readme.md | 2 +- doc/advopt.txt | 2 +- doc/filelist.txt | 6 ++---- doc/manual.md | 8 +++----- doc/mm.md | 2 +- doc/nims.md | 2 +- doc/nimsuggest.md | 2 +- doc/readme.txt | 2 +- doc/sets_fragment.txt | 6 ++---- doc/tools.md | 2 +- doc/tut3.md | 2 +- lib/system.nim | 26 +++++++++++++------------- 12 files changed, 28 insertions(+), 34 deletions(-) diff --git a/compiler/readme.md b/compiler/readme.md index ac47508dc4..4a197991c4 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 8362bbf4cb..e4d11081ae 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 74995f154f..5522414fe6 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 aa53c4512f..1c3e668791 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 9d1fc19559..431517b176 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 2409bb577d..01cdf47c35 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 97cb2b1fab..3d076a6f50 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 7b1a445b50..1157752b93 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 6e0991a9eb..35b1fc0238 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 3eda60b13c..baf7ce3864 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 ccb2eb8091..67f49c8793 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 845ab58e66..94e897b2be 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.} =