diff options
39 files changed, 239 insertions, 216 deletions
diff --git a/doc/astspec.txt b/doc/astspec.txt index 830dc7da9..5d50d82d9 100644 --- a/doc/astspec.txt +++ b/doc/astspec.txt @@ -157,7 +157,7 @@ AST: As a side note, if you choose to use infix operators in a prefix form, the AST behaves as a -[parenthetical function call](./macros.html#calls-expressions-call-with) with +[parenthetical function call](#callsslashexpressions-call-with) with ``nnkAccQuoted``, as follows: Concrete syntax: @@ -237,7 +237,7 @@ Call with raw string literal ---------------------------- This is used, for example, in the ``bindSym`` examples -[here](http://nim-lang.org/docs/manual.html#macros-bindsym) and with +[here](manual.html#macros-bindsym) and with ``re"some regexp"`` in the regular expression module. Concrete syntax: @@ -902,7 +902,7 @@ as the compiler needs to know the type somehow (which it can infer from the given assignment). This is not the same AST for all uses of ``var``. See -[Procedure declaration](http://nim-lang.org/docs/macros.html#statements-procedure-declaration) +[Procedure declaration](macros.html#statements-procedure-declaration) for details. Let section @@ -1361,7 +1361,7 @@ Template declaration Templates (as well as macros, as we'll see) have a slightly expanded AST when compared to procs and iterators. The reason for this is [term-rewriting -macros](http://nim-lang.org/docs/manual.html#term-rewriting-macros). Notice +macros](manual.html#term-rewriting-macros). Notice the ``nnkEmpty()`` as the second argument to ``nnkProcDef`` and ``nnkIteratorDef`` above? That's where the term-rewriting macros go. diff --git a/doc/backends.rst b/doc/backends.rst index f6321942c..2fee1ab9b 100644 --- a/doc/backends.rst +++ b/doc/backends.rst @@ -107,12 +107,13 @@ Nim code calling the backend Nim code can interface with the backend through the `Foreign function interface <manual.html#foreign-function-interface>`_ mainly through the -`importc pragma <manual.html#importc-pragma>`_. The ``importc`` pragma is the -*generic* way of making backend symbols available in Nim and is available -in all the target backends (JavaScript too). The C++ or Objective-C backends -have their respective `ImportCpp <manual.html#implementation-specific-pragmas-importcpp-pragma>`_ and -`ImportObjC <manual.html#implementation-specific-pragmas-importobjc-pragma>`_ pragmas to call methods from -classes. +`importc pragma <manual.html#foreign-function-interface-importc-pragma>`_. +The ``importc`` pragma is the *generic* way of making backend symbols available +in Nim and is available in all the target backends (JavaScript too). The C++ +or Objective-C backends have their respective `ImportCpp +<manual.html#implementation-specific-pragmas-importcpp-pragma>`_ and +`ImportObjC <manual.html#implementation-specific-pragmas-importobjc-pragma>`_ +pragmas to call methods from classes. Whenever you use any of these pragmas you need to integrate native code into your final binary. In the case of JavaScript this is no problem at all, the @@ -124,16 +125,16 @@ statically or dynamically. The preferred way of integrating native code is to use dynamic linking because it allows you to compile Nim programs without the need for having the related development libraries installed. This is done through the `dynlib pragma for import -<manual.html#dynlib-pragma-for-import>`_, though more specific control can be -gained using the `dynlib module <dynlib.html>`_. +<manual.html#foreign-function-interface-dynlib-pragma-for-import>`_, though +more specific control can be gained using the `dynlib module <dynlib.html>`_. The `dynlibOverride <nimc.html#dynliboverride>`_ command line switch allows to avoid dynamic linking if you need to statically link something instead. Nim wrappers designed to statically link source files can use the `compile -pragma <nimc.html#compile-pragma>`_ if there are few sources or providing -them along the Nim code is easier than using a system library. Libraries -installed on the host system can be linked in with the `PassL pragma -<nimc.html#passl-pragma>`_. +pragma <manual.html#implementation-specific-pragmas-compile-pragma>`_ if +there are few sources or providing them along the Nim code is easier than using +a system library. Libraries installed on the host system can be linked in with +the `PassL pragma <manual.html#implementation-specific-pragmas-passl-pragma>`_. To wrap native code, take a look at the `c2nim tool <https://nim-lang.org/docs/c2nim.html>`_ which helps with the process of scanning and transforming header files into a Nim @@ -215,12 +216,12 @@ Backend code calling Nim ------------------------ Backend code can interface with Nim code exposed through the `exportc -pragma <manual.html#exportc-pragma>`_. The ``exportc`` pragma is the *generic* -way of making Nim symbols available to the backends. By default the Nim -compiler will mangle all the Nim symbols to avoid any name collision, so -the most significant thing the ``exportc`` pragma does is maintain the Nim -symbol name, or if specified, use an alternative symbol for the backend in -case the symbol rules don't match. +pragma <manual.html#foreign-function-interface-exportc-pragma>`_. The +``exportc`` pragma is the *generic* way of making Nim symbols available to +the backends. By default the Nim compiler will mangle all the Nim symbols to +avoid any name collision, so the most significant thing the ``exportc`` pragma +does is maintain the Nim symbol name, or if specified, use an alternative +symbol for the backend in case the symbol rules don't match. The JavaScript target doesn't have any further interfacing considerations since it also has garbage collection, but the C targets require you to @@ -329,8 +330,8 @@ Nimcache naming logic The `nimcache`:idx: directory is generated during compilation and will hold either temporary or final files depending on your backend target. The default name for the directory depends on the used backend and on your OS but you can -use the ``--nimcache`` `compiler switch <nimc.html#command-line-switches>`_ to -change it. +use the ``--nimcache`` `compiler switch +<nimc.html#compiler-usage-command-line-switches>`_ to change it. Memory management @@ -349,14 +350,14 @@ Strings and C strings --------------------- The manual mentions that `Nim strings are implicitly convertible to -cstrings <manual.html#cstring-type>`_ which makes interaction usually +cstrings <manual.html#types-cstring-type>`_ which makes interaction usually painless. Most C functions accepting a Nim string converted to a ``cstring`` will likely not need to keep this string around and by the time they return the string won't be needed any more. However, for the rare cases where a Nim string has to be preserved and made available to the C backend as a ``cstring``, you will need to manually prevent the string data from being -freed with `GC_ref <system.html#GC_ref>`_ and `GC_unref -<system.html#GC_unref>`_. +freed with `GC_ref <system.html#GC_ref,string>`_ and `GC_unref +<system.html#GC_unref,string>`_. A similar thing happens with C code invoking Nim code which returns a ``cstring``. Consider the following proc: @@ -382,10 +383,10 @@ Custom data types Just like strings, custom data types that are to be shared between Nim and the backend will need careful consideration of who controls who. If you want to hand a Nim reference to C code, you will need to use `GC_ref -<system.html#GC_ref>`_ to mark the reference as used, so it does not get +<system.html#GC_ref,ref.T>`_ to mark the reference as used, so it does not get freed. And for the C backend you will need to expose the `GC_unref -<system.html#GC_unref>`_ proc to clean up this memory when it is not required -any more. +<system.html#GC_unref,ref.T>`_ proc to clean up this memory when it is not +required any more. Again, if you are wrapping a library which *mallocs* and *frees* data structures, you need to expose the appropriate *free* function to Nim so diff --git a/doc/contributing.rst b/doc/contributing.rst index 9942b68a0..ff623d8cf 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -188,7 +188,7 @@ the old name and introduce a new name: type Barz = enum baz0, baz1 {.deprecated.}, baz2 -See also `Deprecated <https://nim-lang.org/docs/manual.html#pragmas-deprecated-pragma>`_ +See also `Deprecated <manual.html#pragmas-deprecated-pragma>`_ pragma in the manual. @@ -213,8 +213,7 @@ as well as ``testament`` and guarantee they stay in sync. assert "baz".addBar == "bazBar" result = a & "Bar" -See `parentDir <https://nim-lang.github.io/Nim/os.html#parentDir%2Cstring>`_ -example. +See `parentDir <os.html#parentDir,string>`_ example. The RestructuredText Nim uses has a special syntax for including code snippets embedded in documentation; these are not run by ``nim doc`` and therefore are @@ -352,7 +351,8 @@ General commit rules 2. If you introduce changes which affect backwards compatibility, make breaking changes, or have PR which is tagged as ``[feature]``, - the changes should be mentioned in `<changelog.md>`_. + the changes should be mentioned in `the changelog + <https://github.com/nim-lang/Nim/blob/devel/changelog.md>`_. 3. All changes introduced by the commit (diff lines) must be related to the subject of the commit. diff --git a/doc/docgen.rst b/doc/docgen.rst index eb96992b8..4c05702ea 100644 --- a/doc/docgen.rst +++ b/doc/docgen.rst @@ -295,8 +295,8 @@ The relationship of type to suffix is made by the proc ``complexName`` in the ``compiler/docgen.nim`` file. Here are some examples of complex names for symbols in the `system module <system.html>`_. -* ``type SignedInt = int | int8 | int16 | int32 | int64`` **=>** - `#SignedInt <system.html#SignedInt>`_ +* ``type SomeSignedInt = int | int8 | int16 | int32 | int64`` **=>** + `#SomeSignedInt <system.html#SomeSignedInt>`_ * ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>** `#globalRaiseHook <system.html#globalRaiseHook>`_ * ``const NimVersion = "0.0.0"`` **=>** @@ -307,23 +307,25 @@ symbols in the `system module <system.html>`_. `#len,seq[T] <system.html#len,seq[T]>`_ * ``iterator pairs[T](a: seq[T]): tuple[key: int, val: T] {.inline.}`` **=>** `#pairs.i,seq[T] <system.html#pairs.i,seq[T]>`_ -* ``template newException[](exceptn: type; message: string): expr`` **=>** - `#newException.t,type,string - <system.html#newException.t,type,string>`_ +* ``template newException[](exceptn: typedesc; message: string; + parentException: ref Exception = nil): untyped`` **=>** + `#newException.t,typedesc,string,ref.Exception + <system.html#newException.t,typedesc,string,ref.Exception>`_ Index (idx) file format ======================= Files with the ``.idx`` extension are generated when you use the `Index -switch`_ along with commands to generate documentation from source or text -files. You can programatically generate indices with the `setIndexTerm() -<rstgen.html#setIndexTerm>`_ and `writeIndexFile() -<rstgen.html#writeIndexFile>`_ procs. The purpose of ``idx`` files is to hold -the interesting symbols and their HTML references so they can be later -concatenated into a big index file with `mergeIndexes() -<rstgen.html#mergeIndexes>`_. This section documents the file format in -detail. +switch <#related-options-index-switch>`_ along with commands to generate +documentation from source or text files. You can programatically generate +indices with the `setIndexTerm() +<rstgen.html#setIndexTerm,RstGenerator,string,string,string,string,string>`_ +and `writeIndexFile() <rstgen.html#writeIndexFile,RstGenerator,string>`_ procs. +The purpose of ``idx`` files is to hold the interesting symbols and their HTML +references so they can be later concatenated into a big index file with +`mergeIndexes() <rstgen.html#mergeIndexes,string>`_. This section documents +the file format in detail. Index files are line oriented and tab separated (newline and tab characters have to be escaped). Each line represents a record with at least two fields, @@ -368,7 +370,7 @@ final index, and TOC entries found in ``.nim`` files are discarded. Additional resources ==================== -`Nim Compiler User Guide <nimc.html#command-line-switches>`_ +`Nim Compiler User Guide <nimc.html#compiler-usage-command-line-switches>`_ `RST Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ diff --git a/doc/gc.rst b/doc/gc.rst index af849e713..a41a30588 100644 --- a/doc/gc.rst +++ b/doc/gc.rst @@ -164,7 +164,8 @@ you can pass ``--gc:`` on the compile command with the choosed garbage collector The same Nim code can be compiled to use any of the garbage collectors; the Nim syntax generally will not change from one garbage collector to another. -No garbage collector is used for `JavaScript and NodeJS <https://nim-lang.github.io/Nim/backends.html#backends-the-javascript-target>`_ compilation targets. -`NimScript <https://nim-lang.github.io/Nim/nims.html>`_ target uses Nim VM garbage collector. +No garbage collector is used for `JavaScript and NodeJS +<backends.html#backends-the-javascript-target>`_ compilation targets. +`NimScript <nims.html>`_ target uses Nim VM garbage collector. If you are new to Nim and just starting, the default garbage collector is balanced to fit most common use cases. diff --git a/doc/idetools.rst b/doc/idetools.rst index 2ffe46d4b..ebb140c5c 100644 --- a/doc/idetools.rst +++ b/doc/idetools.rst @@ -124,9 +124,9 @@ separators!). The typical usage scenario for this option is to call it after the user has typed the dot character for `the object oriented call -syntax <tut2.html#method-call-syntax>`_. Idetools will try to return -the suggestions sorted first by scope (from innermost to outermost) -and then by item name. +syntax <tut2.html#object-oriented-programming-method-call-syntax>`_. +Idetools will try to return the suggestions sorted first by scope +(from innermost to outermost) and then by item name. Invocation context @@ -359,7 +359,8 @@ defined, since at that point in the file the parser hasn't processed the full line yet. The signature will be returned complete in posterior instances of the method. -Methods imply `dynamic dispatch <tut2.html#dynamic-dispatch>`_ and +Methods imply `dynamic dispatch +<tut2.html#object-oriented-programming-dynamic-dispatch>`_ and idetools performs a static analysis on the code. For this reason idetools may not return the definition of the correct method you are querying because it may be impossible to know until the code diff --git a/doc/koch.rst b/doc/koch.rst index 2140a05f2..0f8434064 100644 --- a/doc/koch.rst +++ b/doc/koch.rst @@ -40,14 +40,15 @@ options: After compilation is finished you will hopefully end up with the nim compiler in the ``bin`` directory. You can add Nim's ``bin`` directory to -your ``$PATH`` or use the `install command`_ to place it where it will be +your ``$PATH`` or use the install command to place it where it will be found. csource command --------------- The `csource`:idx: command builds the C sources for installation. It accepts -the same options as you would pass to the `boot command`_. +the same options as you would pass to the `boot command +<#commands-boot-command>`_. temp command ------------ @@ -55,7 +56,7 @@ temp command The temp command builds the Nim compiler but with a different final name (``nim_temp``), so it doesn't overwrite your normal compiler. You can use this command to test different options, the same you would issue for the `boot -command`_. +command <#commands-boot-command>`_. test command ------------ diff --git a/doc/lib.rst b/doc/lib.rst index 0c9a4e6d4..967e80e05 100644 --- a/doc/lib.rst +++ b/doc/lib.rst @@ -329,7 +329,7 @@ Threading --------- * `threadpool <threadpool.html>`_ - Implements Nim's `spawn <manual.html#parallel-amp-spawn>`_. + Implements Nim's `spawn <manual_experimental.html#parallel-amp-spawn>`_. Parsers diff --git a/doc/manual.rst b/doc/manual.rst index 85f6614df..3a4dc77d8 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -1482,7 +1482,8 @@ order. The *names* of the fields also have to be identical. The assignment operator for tuples copies each component. The default assignment operator for objects copies each component. Overloading -of the assignment operator is described in `type-bound-operations-operator`_. +of the assignment operator is described `here +<manual_experimental.html#type-bound-operations>`_. .. code-block:: nim @@ -2132,7 +2133,7 @@ conversions from ``string`` to ``SQL`` are allowed: Now we have compile-time checking against SQL injection attacks. Since ``"".SQL`` is transformed to ``SQL("")`` no new syntax is needed for nice looking ``SQL`` string literals. The hypothetical ``SQL`` type actually -exists in the library as the `TSqlQuery type <db_sqlite.html#TSqlQuery>`_ of +exists in the library as the `SqlQuery type <db_common.html#SqlQuery>`_ of modules like `db_sqlite <db_sqlite.html>`_. @@ -2643,7 +2644,7 @@ tuple[x: A, y: B, ...] (default(A), default(B), ...) (analogous for objects) array[0..., T] [default(T), ...] range[T] default(T); this may be out of the valid range -T = enum cast[T](0); this may be an invalid value +T = enum cast[T]\(0); this may be an invalid value ============================ ============================================== @@ -3484,8 +3485,8 @@ more argument in this case: assert x == y The command invocation syntax also can't have complex expressions as arguments. -For example: (`anonymous procs`_), ``if``, ``case`` or ``try``. -Function calls with no arguments still needs () to +For example: (`anonymous procs <#procedures-anonymous-procs>`_), ``if``, +``case`` or ``try``. Function calls with no arguments still needs () to distinguish between a call and the function itself as a first class value. @@ -3505,8 +3506,8 @@ Creating closures in loops ~~~~~~~~~~~~~~~~~~~~~~~~~~ Since closures capture local variables by reference it is often not wanted -behavior inside loop bodies. See `closureScope <system.html#closureScope>`_ -for details on how to change this behavior. +behavior inside loop bodies. See `closureScope +<system.html#closureScope.t,untyped>`_ for details on how to change this behavior. Anonymous Procs --------------- @@ -5914,9 +5915,9 @@ or ``ref T`` or ``ptr T`` this means no locations are modified. It is a static error to mark a proc/iterator to have no side effect if the compiler cannot verify this. -As a special semantic rule, the built-in `debugEcho <system.html#debugEcho>`_ -pretends to be free of side effects, so that it can be used for debugging -routines marked as ``noSideEffect``. +As a special semantic rule, the built-in `debugEcho +<system.html#debugEcho,varargs[typed,]>`_ pretends to be free of side effects, +so that it can be used for debugging routines marked as ``noSideEffect``. ``func`` is syntactic sugar for a proc with no side effects: @@ -6187,7 +6188,8 @@ factor. immediate pragma ---------------- -The immediate pragma is obsolete. See `Typed vs untyped parameters`_. +The immediate pragma is obsolete. See `Typed vs untyped parameters +<#templates-typed-vs-untyped-parameters>`_. compilation option pragmas @@ -7051,7 +7053,7 @@ is not set to C, other pragmas are available: * `importcpp <manual.html#implementation-specific-pragmas-importcpp-pragma>`_ * `importobjc <manual.html#implementation-specific-pragmas-importobjc-pragma>`_ - * `importjs <manul.html#implementation-specific-pragmas-importjs-pragma>`_ + * `importjs <manual.html#implementation-specific-pragmas-importjs-pragma>`_ .. code-block:: Nim proc p(s: cstring) {.importc: "prefix$1".} diff --git a/doc/manual_experimental.rst b/doc/manual_experimental.rst index 583f2734f..e0f4831d6 100644 --- a/doc/manual_experimental.rst +++ b/doc/manual_experimental.rst @@ -203,9 +203,10 @@ useful only when interfacing with imported types having such semantics. Automatic dereferencing ======================= -If the `experimental mode <#pragmas-experimental-pragma>`_ is active and no other match -is found, the first argument ``a`` is dereferenced automatically if it's a -pointer type and overloading resolution is tried with ``a[]`` instead. +If the `experimental mode <manual.html#pragmas-experimental-pragma>`_ is active +and no other match is found, the first argument ``a`` is dereferenced +automatically if it's a pointer type and overloading resolution is tried +with ``a[]`` instead. Automatic self insertions @@ -814,7 +815,7 @@ This mechanism will be used by most data structures that support shared memory like channels to implement thread safe automatic memory management. The builtin ``deepCopy`` can even clone closures and their environments. See -the documentation of `spawn`_ for details. +the documentation of `spawn <#parallel-amp-spawn-spawn-statement>`_ for details. Case statement macros diff --git a/doc/nimc.rst b/doc/nimc.rst index d53e3f310..c59653b34 100644 --- a/doc/nimc.rst +++ b/doc/nimc.rst @@ -114,7 +114,8 @@ Level Description ===== ============================================ 0 Minimal output level for the compiler. 1 Displays compilation of all the compiled files, including those imported - by other modules or through the `compile pragma<#compile-pragma>`_. + by other modules or through the `compile pragma + <manual.html#implementation-specific-pragmas-compile-pragma>`_. This is the default level. 2 Displays compilation statistics, enumerates the dynamic libraries that will be loaded by the final binary and dumps to @@ -130,9 +131,10 @@ Compile time symbols Through the ``-d:x`` or ``--define:x`` switch you can define compile time symbols for conditional compilation. The defined switches can be checked in -source code with the `when statement <manual.html#when-statement>`_ and -`defined proc <system.html#defined>`_. The typical use of this switch is to -enable builds in release mode (``-d:release``) where optimizations are +source code with the `when statement +<manual.html#statements-and-expressions-when-statement>`_ and +`defined proc <system.html#defined,untyped>`_. The typical use of this switch is +to enable builds in release mode (``-d:release``) where optimizations are enabled for better performance. Another common use is the ``-d:ssl`` switch to activate SSL sockets. @@ -215,7 +217,7 @@ The ``_r`` suffix is used for release builds, ``_d`` is for debug builds. This makes it easy to delete all generated files. The ``--nimcache`` -`compiler switch <nimc.html#command-line-switches>`_ can be used to +`compiler switch <#compiler-usage-command-line-switches>`_ can be used to to change the ``nimcache`` directory. However, the generated C code is not platform independent. C code generated for diff --git a/doc/nimsuggest.rst b/doc/nimsuggest.rst index 0b6839b53..a5d0d65b9 100644 --- a/doc/nimsuggest.rst +++ b/doc/nimsuggest.rst @@ -105,9 +105,9 @@ completion symbols at some point in the file. The typical usage scenario for this option is to call it after the user has typed the dot character for `the object oriented call -syntax <tut2.html#method-call-syntax>`_. Nimsuggest will try to return -the suggestions sorted first by scope (from innermost to outermost) -and then by item name. +syntax <tut2.html#object-oriented-programming-method-call-syntax>`_. +Nimsuggest will try to return the suggestions sorted first by scope +(from innermost to outermost) and then by item name. Invocation context diff --git a/doc/sets_fragment.txt b/doc/sets_fragment.txt index b36b4b7bd..8436190a0 100644 --- a/doc/sets_fragment.txt +++ b/doc/sets_fragment.txt @@ -83,4 +83,4 @@ Note how the set turns enum values into powers of 2. If using enums and sets with C, use distinct cint. For interoperability with C see also the -`bitsize pragma <#implementation-specific-pragmas-bitsize-pragma>`_. +`bitsize pragma <manual.html#implementation-specific-pragmas-bitsize-pragma>`_. diff --git a/doc/tools.rst b/doc/tools.rst index f407420b0..4920e94a2 100644 --- a/doc/tools.rst +++ b/doc/tools.rst @@ -20,7 +20,7 @@ The standard distribution ships with the following tools: - | `C2nim <https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst>`_ | C to Nim source converter. Translates C header files to Nim. -- | `niminst <https://nim-lang.org/docs/niminst.html>`_ +- | `niminst <niminst.html>`_ | niminst is a tool to generate an installer for a Nim program. - | `nimgrep <nimgrep.html>`_ diff --git a/doc/tut1.rst b/doc/tut1.rst index fc87fa663..bfe87a40e 100644 --- a/doc/tut1.rst +++ b/doc/tut1.rst @@ -67,8 +67,8 @@ done with spaces only, tabulators are not allowed. String literals are enclosed in double quotes. The ``var`` statement declares a new variable named ``name`` of type ``string`` with the value that is -returned by the `readLine <system.html#readLine,File>`_ procedure. Since the -compiler knows that `readLine <system.html#readLine,File>`_ returns a string, +returned by the `readLine <io.html#readLine,File>`_ procedure. Since the +compiler knows that `readLine <io.html#readLine,File>`_ returns a string, you can leave out the type in the declaration (this is called `local type inference`:idx:). So this will work too: @@ -80,7 +80,7 @@ Note that this is basically the only form of type inference that exists in Nim: it is a good compromise between brevity and readability. The "hello world" program contains several identifiers that are already known -to the compiler: ``echo``, `readLine <system.html#readLine,File>`_, etc. +to the compiler: ``echo``, `readLine <io.html#readLine,File>`_, etc. These built-ins are declared in the system_ module which is implicitly imported by any other module. @@ -326,10 +326,11 @@ the compiler that for every other value nothing should be done: of 3, 8: echo "The number is 3 or 8" else: discard -The empty `discard statement`_ is a *do nothing* statement. The compiler knows -that a case statement with an else part cannot fail and thus the error -disappears. Note that it is impossible to cover all possible string values: -that is why string cases always need an ``else`` branch. +The empty `discard statement <#procedures-discard-statement>`_ is a *do +nothing* statement. The compiler knows that a case statement with an else part +cannot fail and thus the error disappears. Note that it is impossible to cover +all possible string values: that is why string cases always need an ``else`` +branch. In general the case statement is used for subrange types or enumerations where it is of great help that the compiler checks that you covered any possible @@ -359,8 +360,8 @@ For statement ------------- The ``for`` statement is a construct to loop over any element an *iterator* -provides. The example uses the built-in `countup <system.html#countup>`_ -iterator: +provides. The example uses the built-in `countup +<system.html#countup.i,T,T,Positive>`_ iterator: .. code-block:: nim :test: "nim c $1" @@ -371,8 +372,8 @@ iterator: The variable ``i`` is implicitly declared by the ``for`` loop and has the type ``int``, because that is what `countup -<system.html#countup>`_ returns. ``i`` runs through the values 1, 2, .., 10. -Each value is ``echo``-ed. This code does the same: +<system.html#countup.i,T,T,Positive>`_ returns. ``i`` runs through the values +1, 2, .., 10. Each value is ``echo``-ed. This code does the same: .. code-block:: nim echo "Counting to 10: " @@ -391,7 +392,7 @@ Counting down can be achieved as easily (but is less often needed): # --> Outputs 10 9 8 7 6 5 4 3 2 1 on different lines Since counting up occurs so often in programs, Nim also has a `.. -<system.html#...i,S,T>`_ iterator that does the same: +<system.html#...i,T,T>`_ iterator that does the same: .. code-block:: nim for i in 1..10: @@ -570,10 +571,10 @@ an expression is allowed: Procedures ========== -To define new commands like `echo <system.html#echo>`_ and `readLine -<system.html#readLine,File>`_ in the examples, the concept of a `procedure` -is needed. (Some languages call them *methods* or *functions*.) In Nim new -procedures are defined with the ``proc`` keyword: +To define new commands like `echo <system.html#echo,varargs[typed,]>`_ +and `readLine <io.html#readLine,File>`_ in the examples, the concept of a +`procedure` is needed. (Some languages call them *methods* or *functions*.) +In Nim new procedures are defined with the ``proc`` keyword: .. code-block:: nim :test: "nim c $1" @@ -753,7 +754,7 @@ Nim provides the ability to overload procedures similar to C++: echo toString(13) # calls the toString(x: int) proc echo toString(true) # calls the toString(x: bool) proc -(Note that ``toString`` is usually the `$ <system.html#$>`_ operator in +(Note that ``toString`` is usually the `$ <dollars.html>`_ operator in Nim.) The compiler chooses the most appropriate proc for the ``toString`` calls. How this overloading resolution algorithm works exactly is not discussed here (it will be specified in the manual soon). However, it does @@ -845,8 +846,8 @@ Let's return to the simple counting example: for i in countup(1, 10): echo i -Can a `countup <system.html#countup>`_ proc be written that supports this -loop? Lets try: +Can a `countup <system.html#countup.i,T,T,Positive>`_ proc be written that +supports this loop? Lets try: .. code-block:: nim proc countup(a, b: int): int = @@ -1010,8 +1011,8 @@ floats and follow the IEEE-754 standard. Automatic type conversion in expressions with different kinds of floating point types is performed: the smaller type is converted to the larger. Integer types are **not** converted to floating point types automatically, nor vice -versa. Use the `toInt <system.html#toInt>`_ and `toFloat <system.html#toFloat>`_ -procs for these conversions. +versa. Use the `toInt <system.html#toInt,float>`_ and +`toFloat <system.html#toFloat,int>`_ procs for these conversions. Type Conversion @@ -1031,13 +1032,13 @@ type as a function: Internal type representation ============================ -As mentioned earlier, the built-in `$ <system.html#$>`_ (stringify) operator +As mentioned earlier, the built-in `$ <dollars.html>`_ (stringify) operator turns any basic type into a string, which you can then print to the console using the ``echo`` proc. However, advanced types, and your own custom types, won't work with the ``$`` operator until you define it for them. Sometimes you just want to debug the current value of a complex type without having to write its ``$`` operator. You can use then the `repr -<system.html#repr>`_ proc which works with any type and even complex data +<system.html#repr,T>`_ proc which works with any type and even complex data graphs with cycles. The following example shows that even for basic types there is a difference between the ``$`` and ``repr`` outputs: @@ -1127,9 +1128,9 @@ Operation Comment ``pred(x, n)`` returns the `n`'th predecessor of `x` ----------------- -------------------------------------------------------- -The `inc <system.html#inc>`_, `dec <system.html#dec>`_, `succ -<system.html#succ>`_ and `pred <system.html#pred>`_ operations can fail by -raising an `EOutOfRange` or `EOverflow` exception. (If the code has been +The `inc <system.html#inc,T,int>`_, `dec <system.html#dec,T,int>`_, `succ +<system.html#succ,T,int>`_ and `pred <system.html#pred,T,int>`_ operations can +fail by raising an `EOutOfRange` or `EOverflow` exception. (If the code has been compiled with the proper runtime checks turned on.) @@ -1150,8 +1151,8 @@ compile-time or runtime error. Assignments from the base type to one of its subrange types (and vice versa) are allowed. The ``system`` module defines the important `Natural <system.html#Natural>`_ -type as ``range[0..high(int)]`` (`high <system.html#high>`_ returns the -maximal value). Other programming languages may suggest the use of unsigned +type as ``range[0..high(int)]`` (`high <system.html#high,typedesc[T]>`_ returns +the maximal value). Other programming languages may suggest the use of unsigned integers for natural numbers. This is often **unwise**: you don't want unsigned arithmetic (which wraps around) just because the numbers cannot be negative. Nim's ``Natural`` type helps to avoid this common programming error. @@ -1189,8 +1190,9 @@ Arrays are value types, like any other Nim type. The assignment operator copies the whole array contents. The built-in `len <system.html#len,TOpenArray>`_ proc returns the array's -length. `low(a) <system.html#low>`_ returns the lowest valid index for the -array `a` and `high(a) <system.html#high>`_ the highest valid index. +length. `low(a) <system.html#low,openArray[T]>`_ returns the lowest valid index +for the array `a` and `high(a) <system.html#high,openArray[T]>`_ the highest +valid index. .. code-block:: nim :test: "nim c $1" @@ -1265,9 +1267,9 @@ during runtime (like strings). Since sequences are resizable they are always allocated on the heap and garbage collected. Sequences are always indexed with an ``int`` starting at position 0. The `len -<system.html#len,seq[T]>`_, `low <system.html#low>`_ and `high -<system.html#high>`_ operations are available for sequences too. The notation -``x[i]`` can be used to access the i-th element of ``x``. +<system.html#len,seq[T]>`_, `low <system.html#low,openArray[T]>`_ and `high +<system.html#high,openArray[T]>`_ operations are available for sequences too. +The notation ``x[i]`` can be used to access the i-th element of ``x``. Sequences can be constructed by the array constructor ``[]`` in conjunction with the array to sequence operator ``@``. Another way to allocate space for @@ -1318,10 +1320,10 @@ Open arrays Often fixed size arrays turn out to be too inflexible; procedures should be able to deal with arrays of different sizes. The `openarray`:idx: type allows this. Openarrays are always indexed with an ``int`` starting at position 0. -The `len <system.html#len,TOpenArray>`_, `low <system.html#low>`_ and `high -<system.html#high>`_ operations are available for open arrays too. Any array -with a compatible base type can be passed to an openarray parameter, the index -type does not matter. +The `len <system.html#len,TOpenArray>`_, `low <system.html#low,openArray[T]>`_ +and `high <system.html#high,openArray[T]>`_ operations are available for open +arrays too. Any array with a compatible base type can be passed to an +openarray parameter, the index type does not matter. .. code-block:: nim :test: "nim c $1" @@ -1377,8 +1379,8 @@ type conversions in this context: # is transformed by the compiler to: myWriteln(stdout, [$123, $"abc", $4.0]) -In this example `$ <system.html#$>`_ is applied to any argument that is passed -to the parameter ``a``. Note that `$ <system.html#$>`_ applied to strings is a +In this example `$ <dollars.html>`_ is applied to any argument that is passed +to the parameter ``a``. Note that `$ <dollars.html>`_ applied to strings is a nop. @@ -1561,8 +1563,8 @@ having the same field types. Tuples can be *unpacked* during variable assignment (and only then!). This can be handy to assign directly the fields of the tuples to individually named -variables. An example of this is the `splitFile <os.html#splitFile>`_ proc -from the `os module <os.html>`_ which returns the directory, name and +variables. An example of this is the `splitFile <os.html#splitFile,string>`_ +proc from the `os module <os.html>`_ which returns the directory, name and extension of a path at the same time. For tuple unpacking to work you must use parentheses around the values you want to assign the unpacking to, otherwise you will be assigning the same value to all the individual diff --git a/lib/core/macros.nim b/lib/core/macros.nim index a3f362f97..cd4a3c48f 100644 --- a/lib/core/macros.nim +++ b/lib/core/macros.nim @@ -13,8 +13,8 @@ include "system/inclrtl" ## tree (`AST`:idx:). Macros operate on this tree. ## ## See also: -## * `macros tutorial <https://nim-lang.github.io/Nim/tut3.html>`_ -## * `macros section in Nim manual <https://nim-lang.github.io/Nim/manual.html#macros>`_ +## * `macros tutorial <tut3.html>`_ +## * `macros section in Nim manual <manual.html#macros>`_ ## .. include:: ../../doc/astspec.txt diff --git a/lib/js/dom.nim b/lib/js/dom.nim index efe281ce5..53d9cd204 100644 --- a/lib/js/dom.nim +++ b/lib/js/dom.nim @@ -8,7 +8,7 @@ # ## Declaration of the Document Object Model for the `JavaScript backend -## <backends.html#the-javascript-target>`_. +## <backends.html#backends-the-javascript-target>`_. when not defined(js) and not defined(Nimdoc): {.error: "This module only works on the JavaScript platform".} diff --git a/lib/js/jsconsole.nim b/lib/js/jsconsole.nim index 617cbebf1..199a5607e 100644 --- a/lib/js/jsconsole.nim +++ b/lib/js/jsconsole.nim @@ -8,7 +8,7 @@ # ## Wrapper for the `console` object for the `JavaScript backend -## <backends.html#the-javascript-target>`_. +## <backends.html#backends-the-javascript-target>`_. when not defined(js) and not defined(Nimdoc): {.error: "This module only works on the JavaScript platform".} diff --git a/lib/packages/docutils/rstgen.nim b/lib/packages/docutils/rstgen.nim index e5536868b..f9fd9e32b 100644 --- a/lib/packages/docutils/rstgen.nim +++ b/lib/packages/docutils/rstgen.nim @@ -154,7 +154,8 @@ proc writeIndexFile*(g: var RstGenerator, outfile: string) = ## Writes the current index buffer to the specified output file. ## ## You previously need to add entries to the index with the `setIndexTerm() - ## <#setIndexTerm>`_ proc. If the index is empty the file won't be created. + ## <#setIndexTerm,RstGenerator,string,string,string,string,string>`_ proc. + ## If the index is empty the file won't be created. if g.theIndex.len > 0: writeFile(outfile, g.theIndex) proc addXmlChar(dest: var string, c: char) = @@ -308,7 +309,7 @@ proc setIndexTerm*(d: var RstGenerator, htmlFile, id, term: string, ## The `id` will be appended with a hash character only if its length is not ## zero, otherwise no specific anchor will be generated. In general you ## should only pass an empty `id` value for the title of standalone rst - ## documents (they are special for the `mergeIndexes() <#mergeIndexes>`_ + ## documents (they are special for the `mergeIndexes() <#mergeIndexes,string>`_ ## proc, see `Index (idx) file format <docgen.html#index-idx-file-format>`_ ## for more information). Unlike other index terms, title entries are ## inserted at the beginning of the accumulated buffer to maintain a logical @@ -318,8 +319,9 @@ proc setIndexTerm*(d: var RstGenerator, htmlFile, id, term: string, ## columns with their contents will be added. ## ## The index won't be written to disk unless you call `writeIndexFile() - ## <#writeIndexFile>`_. The purpose of the index is documented in the `docgen - ## tools guide <docgen.html#index-switch>`_. + ## <#writeIndexFile,RstGenerator,string>`_. The purpose of the index is + ## documented in the `docgen tools guide + ## <docgen.html#related-options-index-switch>`_. var entry = term isTitle = false @@ -472,8 +474,8 @@ proc generateSymbolIndex(symbols: seq[IndexEntry]): string = proc isDocumentationTitle(hyperlink: string): bool = ## Returns true if the hyperlink is actually a documentation title. ## - ## Documentation titles lack the hash. See `mergeIndexes() <#mergeIndexes>`_ - ## for a more detailed explanation. + ## Documentation titles lack the hash. See `mergeIndexes() + ## <#mergeIndexes,string>`_ for a more detailed explanation. result = hyperlink.find('#') < 0 proc stripTocLevel(s: string): tuple[level: int, text: string] = @@ -650,8 +652,10 @@ proc mergeIndexes*(dir: string): string = ## This proc will first scan `dir` for index files with the ``.idx`` ## extension previously created by commands like ``nim doc|rst2html`` ## which use the ``--index:on`` switch. These index files are the result of - ## calls to `setIndexTerm() <#setIndexTerm>`_ and `writeIndexFile() - ## <#writeIndexFile>`_, so they are simple tab separated files. + ## calls to `setIndexTerm() + ## <#setIndexTerm,RstGenerator,string,string,string,string,string>`_ + ## and `writeIndexFile() <#writeIndexFile,RstGenerator,string>`_, so they are + ## simple tab separated files. ## ## As convention this proc will split index files into two categories: ## documentation and API. API indices will be all joined together into a diff --git a/lib/posix/posix.nim b/lib/posix/posix.nim index 8fcb9cb5c..044e0448f 100644 --- a/lib/posix/posix.nim +++ b/lib/posix/posix.nim @@ -584,7 +584,7 @@ proc fchmod*(a1: cint, a2: Mode): cint {.importc, header: "<sys/stat.h>".} proc fstat*(a1: cint, a2: var Stat): cint {.importc, header: "<sys/stat.h>".} proc lstat*(a1: cstring, a2: var Stat): cint {.importc, header: "<sys/stat.h>".} proc mkdir*(a1: cstring, a2: Mode): cint {.importc, header: "<sys/stat.h>".} - ## Use `os.createDir() <os.html#createDir>`_ and similar. + ## Use `os.createDir() <os.html#createDir,string>`_ and similar. proc mkfifo*(a1: cstring, a2: Mode): cint {.importc, header: "<sys/stat.h>".} proc mknod*(a1: cstring, a2: Mode, a3: Dev): cint {. diff --git a/lib/pure/algorithm.nim b/lib/pure/algorithm.nim index 522ff1b16..d40b2fd63 100644 --- a/lib/pure/algorithm.nim +++ b/lib/pure/algorithm.nim @@ -392,7 +392,7 @@ func sort*[T](a: var openArray[T], ## sort(myStrArray, system.cmp) ## ## You can inline adhoc comparison procs with the `do notation - ## <manual.html#procedures-do-notation>`_. Example: + ## <manual_experimental.html#do-notation>`_. Example: ## ## .. code-block:: nim ## diff --git a/lib/pure/asyncstreams.nim b/lib/pure/asyncstreams.nim index 42cdd7d13..44e73003e 100644 --- a/lib/pure/asyncstreams.nim +++ b/lib/pure/asyncstreams.nim @@ -60,7 +60,7 @@ proc `callback=`*[T](future: FutureStream[T], proc finished*[T](future: FutureStream[T]): bool = ## Check if a ``FutureStream`` is finished. ``true`` value means that - ## no more data will be placed inside the stream _and_ that there is + ## no more data will be placed inside the stream *and* that there is ## no data waiting to be retrieved. result = future.finished and future.queue.len == 0 diff --git a/lib/pure/base64.nim b/lib/pure/base64.nim index 615af24d1..65cae2a1d 100644 --- a/lib/pure/base64.nim +++ b/lib/pure/base64.nim @@ -175,8 +175,8 @@ proc decode*(s: string): string = ## The initial whitespace is skipped. ## ## **See also:** - ## * `encode proc<#encode,openArray[T],int,string>`_ for encoding an openarray - ## * `encode proc<#encode,string,int,string>`_ for encoding a string + ## * `encode proc<#encode,openArray[T]>`_ for encoding an openarray + ## * `encode proc<#encode,string>`_ for encoding a string runnableExamples: assert decode("SGVsbG8gV29ybGQ=") == "Hello World" assert decode(" SGVsbG8gV29ybGQ=") == "Hello World" diff --git a/lib/pure/collections/lists.nim b/lib/pure/collections/lists.nim index 4118290b6..b95cfffc0 100644 --- a/lib/pure/collections/lists.nim +++ b/lib/pure/collections/lists.nim @@ -69,8 +69,8 @@ ## See also ## ======== ## -## * `deques module <#deques.html>`_ for double-ended queues -## * `sharedlist module <#sharedlist.html>`_ for shared singly-linked lists +## * `deques module <deques.html>`_ for double-ended queues +## * `sharedlist module <sharedlist.html>`_ for shared singly-linked lists when not defined(nimhygiene): diff --git a/lib/pure/collections/sequtils.nim b/lib/pure/collections/sequtils.nim index 00bb0300d..9ea8c44f7 100644 --- a/lib/pure/collections/sequtils.nim +++ b/lib/pure/collections/sequtils.nim @@ -35,7 +35,7 @@ ## `filterIt<#filterIt.t,untyped,untyped>`_, etc.) ## ## The chaining of functions is possible thanks to the -## `method call syntax<manual.html#procs-method-call-syntax>`_. +## `method call syntax<manual.html#procedures-method-call-syntax>`_. ## ## .. code-block:: ## import sequtils, sugar diff --git a/lib/pure/collections/sets.nim b/lib/pure/collections/sets.nim index 4b896b12b..930b7f0ed 100644 --- a/lib/pure/collections/sets.nim +++ b/lib/pure/collections/sets.nim @@ -99,8 +99,8 @@ proc init*[A](s: var HashSet[A], initialSize = defaultInitialSize) = ## ## The `initialSize` parameter needs to be a power of two (default: 64). ## If you need to accept runtime values for this, you can use - ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo>`_ or `rightSize proc - ## <#rightSize,Natural>`_ from this module. + ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo,int>`_ or + ## `rightSize proc <#rightSize,Natural>`_ from this module. ## ## Starting from Nim v0.20, sets are initialized by default and it is ## not necessary to call this function explicitly. @@ -645,8 +645,8 @@ proc init*[A](s: var OrderedSet[A], initialSize = defaultInitialSize) = ## ## The `initialSize` parameter needs to be a power of two (default: 64). ## If you need to accept runtime values for this, you can use - ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo>`_ or `rightSize proc - ## <#rightSize,Natural>`_ from this module. + ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo,int>`_ or + ## `rightSize proc <#rightSize,Natural>`_ from this module. ## ## Starting from Nim v0.20, sets are initialized by default and it is ## not necessary to call this function explicitly. diff --git a/lib/pure/collections/tables.nim b/lib/pure/collections/tables.nim index 3c91ba9c7..7d1633e7d 100644 --- a/lib/pure/collections/tables.nim +++ b/lib/pure/collections/tables.nim @@ -134,7 +134,8 @@ ## # 'a': 5, 'b': 2, 'c': 1, 'd': 1, 'r': 2} ## ## The same could have been achieved by manually iterating over a container -## and increasing each key's value with `inc proc<#inc,CountTable[A],A,int>`_: +## and increasing each key's value with `inc proc +## <#inc,CountTable[A],A,Positive>`_: ## ## .. code-block:: ## import tables @@ -2236,7 +2237,7 @@ proc `[]=`*[A](t: var CountTable[A], key: A, val: int) = ## ## See also: ## * `[] proc<#[],CountTable[A],A>`_ for retrieving a value of a key - ## * `inc proc<#inc,CountTable[A],A,int>`_ for incrementing a + ## * `inc proc<#inc,CountTable[A],A,Positive>`_ for incrementing a ## value of a key assert(not t.isSorted, "CountTable must not be used after sorting") assert val >= 0 diff --git a/lib/pure/concurrency/threadpool.nim b/lib/pure/concurrency/threadpool.nim index d6506cd76..1f7df7c00 100644 --- a/lib/pure/concurrency/threadpool.nim +++ b/lib/pure/concurrency/threadpool.nim @@ -487,7 +487,7 @@ proc parallel*(body: untyped) {.magic: "Parallel".} ## ## ``body`` has to be in a DSL that is a particular subset of the language. ## - ## Please refer to `the manual <manual.html#parallel-amp-spawn>`_ + ## Please refer to `the manual <manual_experimental.html#parallel-amp-spawn>`_ ## for further information. var diff --git a/lib/pure/htmlgen.nim b/lib/pure/htmlgen.nim index ebd46df53..4887e6144 100644 --- a/lib/pure/htmlgen.nim +++ b/lib/pure/htmlgen.nim @@ -11,7 +11,7 @@ ## as ``from htmlgen import nil`` and then fully qualify the macros. ## ## *Note*: The Karax project (``nimble install karax``) has a better -## way to achieve the same, see `https://github.com/pragmagic/karax/blob/master/tests/nativehtmlgen.nim`_ +## way to achieve the same, see https://github.com/pragmagic/karax/blob/master/tests/nativehtmlgen.nim ## for an example. ## ## diff --git a/lib/pure/math.nim b/lib/pure/math.nim index 54f5bc33e..ee78b6c91 100644 --- a/lib/pure/math.nim +++ b/lib/pure/math.nim @@ -35,7 +35,7 @@ ## # nan (use `complex` module) ## ## This module is available for the `JavaScript target -## <backends.html#the-javascript-target>`_. +## <backends.html#backends-the-javascript-target>`_. ## ## **See also:** ## * `complex module<complex.html>`_ for complex numbers and their diff --git a/lib/pure/memfiles.nim b/lib/pure/memfiles.nim index 411df1456..152b03ec6 100644 --- a/lib/pure/memfiles.nim +++ b/lib/pure/memfiles.nim @@ -431,9 +431,9 @@ iterator memSlices*(mfile: MemFile, delim = '\l', eat = '\r'): MemSlice {.inline iterator lines*(mfile: MemFile, buf: var TaintedString, delim = '\l', eat = '\r'): TaintedString {.inline.} = ## Replace contents of passed buffer with each new line, like - ## `readLine(File) <system.html#readLine,File,TaintedString>`_. - ## `delim`, `eat`, and delimiting logic is exactly as for - ## `memSlices <#memSlices>`_, but Nim strings are returned. + ## `readLine(File) <io.html#readLine,File,TaintedString>`_. + ## `delim`, `eat`, and delimiting logic is exactly as for `memSlices + ## <#memSlices.i,MemFile,char,char>`_, but Nim strings are returned. ## ## Example: ## @@ -450,9 +450,9 @@ iterator lines*(mfile: MemFile, buf: var TaintedString, delim = '\l', iterator lines*(mfile: MemFile, delim = '\l', eat = '\r'): TaintedString {.inline.} = ## Return each line in a file as a Nim string, like - ## `lines(File) <system.html#lines.i,File>`_. - ## `delim`, `eat`, and delimiting logic is exactly as for - ## `memSlices <#memSlices>`_, but Nim strings are returned. + ## `lines(File) <io.html#lines.i,File>`_. + ## `delim`, `eat`, and delimiting logic is exactly as for `memSlices + ## <#memSlices.i,MemFile,char,char>`_, but Nim strings are returned. ## ## Example: ## diff --git a/lib/pure/parsecsv.nim b/lib/pure/parsecsv.nim index 741ce33b8..44703e3f8 100644 --- a/lib/pure/parsecsv.nim +++ b/lib/pure/parsecsv.nim @@ -57,7 +57,7 @@ ## ======== ## ## * `streams module <streams.html>`_ for using -## `open proc <#open,CsvParser,Stream,string,Char,Char,Char>`_ +## `open proc <#open,CsvParser,Stream,string,char,char,char>`_ ## and other stream processing (like `close proc <streams.html#close,Stream>`_) ## * `parseopt module <parseopt.html>`_ for a command line parser ## * `parsecfg module <parsecfg.html>`_ for a configuration file parser @@ -117,7 +117,7 @@ proc open*(my: var CsvParser, input: Stream, filename: string, ## `separator` is ignored. ## ## See also: - ## * `open proc <#open,CsvParser,string,Char,Char,Char>`_ which creates the + ## * `open proc <#open,CsvParser,string,char,char,char>`_ which creates the ## file stream for you runnableExamples: import streams @@ -139,7 +139,7 @@ proc open*(my: var CsvParser, input: Stream, filename: string, proc open*(my: var CsvParser, filename: string, separator = ',', quote = '"', escape = '\0', skipInitialSpace = false) = - ## Similar to the `other open proc<#open,CsvParser,Stream,string,Char,Char,Char>`_, + ## Similar to the `other open proc<#open,CsvParser,Stream,string,char,char,char>`_, ## but creates the file stream for you. runnableExamples: from os import removeFile diff --git a/lib/pure/random.nim b/lib/pure/random.nim index 72e9f91f0..7283547d6 100644 --- a/lib/pure/random.nim +++ b/lib/pure/random.nim @@ -75,7 +75,7 @@ ## generator ## * `stats module<stats.html>`_ for statistical analysis ## * `list of cryptographic and hashing modules -## <lib.html#pure-libraries-cryptography-and-hashing>`_ +## <lib.html#pure-libraries-hashing>`_ ## in the standard library import algorithm #For upperBound diff --git a/lib/pure/streams.nim b/lib/pure/streams.nim index 3850d10e2..c9547eee1 100644 --- a/lib/pure/streams.nim +++ b/lib/pure/streams.nim @@ -1223,7 +1223,7 @@ else: ## * `newStringStream proc <#newStringStream,string>`_ creates a new stream ## from string. ## * `newFileStream proc <#newFileStream,string,FileMode,int>`_ is the same - ## as using `open proc <system.html#open,File,string,FileMode,int>`_ + ## as using `open proc <io.html#open,File,string,FileMode,int>`_ ## on Examples. ## * `openFileStream proc <#openFileStream,string,FileMode,int>`_ creates a ## file stream from the file name and the mode. diff --git a/lib/pure/strutils.nim b/lib/pure/strutils.nim index 69cb1efd5..e5445fe7e 100644 --- a/lib/pure/strutils.nim +++ b/lib/pure/strutils.nim @@ -50,7 +50,7 @@ ## "Beetlejuice Beetlejuice Beetlejuice" ## ## This module is available for the `JavaScript target -## <backends.html#the-javascript-target>`_. +## <backends.html#backends-the-javascript-target>`_. ## ## ---- ## @@ -209,7 +209,7 @@ proc toLowerAscii*(c: char): char {.noSideEffect, procvar, ## Returns the lower case version of character ``c``. ## ## This works only for the letters ``A-Z``. See `unicode.toLower - ## <unicode.html#toLower>`_ for a version that works for any Unicode + ## <unicode.html#toLower,Rune>`_ for a version that works for any Unicode ## character. ## ## See also: @@ -233,7 +233,7 @@ proc toLowerAscii*(s: string): string {.noSideEffect, procvar, ## Converts string `s` into lower case. ## ## This works only for the letters ``A-Z``. See `unicode.toLower - ## <unicode.html#toLower>`_ for a version that works for any Unicode + ## <unicode.html#toLower,string>`_ for a version that works for any Unicode ## character. ## ## See also: @@ -247,7 +247,7 @@ proc toUpperAscii*(c: char): char {.noSideEffect, procvar, ## Converts character `c` into upper case. ## ## This works only for the letters ``A-Z``. See `unicode.toUpper - ## <unicode.html#toUpper>`_ for a version that works for any Unicode + ## <unicode.html#toUpper,Rune>`_ for a version that works for any Unicode ## character. ## ## See also: @@ -267,7 +267,7 @@ proc toUpperAscii*(s: string): string {.noSideEffect, procvar, ## Converts string `s` into upper case. ## ## This works only for the letters ``A-Z``. See `unicode.toUpper - ## <unicode.html#toUpper>`_ for a version that works for any Unicode + ## <unicode.html#toUpper,string>`_ for a version that works for any Unicode ## character. ## ## See also: @@ -631,10 +631,10 @@ iterator rsplit*(s: string, sep: string, maxsplit: int = -1, iterator splitLines*(s: string, keepEol = false): string = ## Splits the string `s` into its containing lines. ## - ## Every `character literal <manual.html#character-literals>`_ newline - ## combination (CR, LF, CR-LF) is supported. The result strings contain no - ## trailing end of line characters unless parameter ``keepEol`` is set to - ## ``true``. + ## Every `character literal <manual.html#lexical-analysis-character-literals>`_ + ## newline combination (CR, LF, CR-LF) is supported. The result strings + ## contain no trailing end of line characters unless parameter ``keepEol`` + ## is set to ``true``. ## ## Example: ## @@ -1308,8 +1308,8 @@ proc spaces*(n: Natural): string {.inline.} = ## to left align strings. ## ## See also: - ## * `align proc<#align,string,Natural,Char>`_ - ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_ + ## * `align proc<#align,string,Natural,char>`_ + ## * `alignLeft proc<#alignLeft,string,Natural,char>`_ ## * `indent proc<#indent,string,Natural,string>`_ ## * `center proc<#center,string,int,char>`_ runnableExamples: @@ -1330,10 +1330,10 @@ proc align*(s: string, count: Natural, padding = ' '): string {. ## `padding` characters (by default spaces) are added before `s` resulting in ## right alignment. If ``s.len >= count``, no spaces are added and `s` is ## returned unchanged. If you need to left align a string use the `alignLeft - ## proc <#alignLeft,string,Natural,Char>`_. + ## proc <#alignLeft,string,Natural,char>`_. ## ## See also: - ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_ + ## * `alignLeft proc<#alignLeft,string,Natural,char>`_ ## * `spaces proc<#spaces,Natural>`_ ## * `indent proc<#indent,string,Natural,string>`_ ## * `center proc<#center,string,int,char>`_ @@ -1357,10 +1357,10 @@ proc alignLeft*(s: string, count: Natural, padding = ' '): string {. ## `padding` characters (by default spaces) are added after `s` resulting in ## left alignment. If ``s.len >= count``, no spaces are added and `s` is ## returned unchanged. If you need to right align a string use the `align - ## proc <#align,string,Natural,Char>`_. + ## proc <#align,string,Natural,char>`_. ## ## See also: - ## * `align proc<#align,string,Natural,Char>`_ + ## * `align proc<#align,string,Natural,char>`_ ## * `spaces proc<#spaces,Natural>`_ ## * `indent proc<#indent,string,Natural,string>`_ ## * `center proc<#center,string,int,char>`_ @@ -1387,8 +1387,8 @@ proc center*(s: string, width: int, fillChar: char = ' '): string {. ## to `s.len`. ## ## See also: - ## * `align proc<#align,string,Natural,Char>`_ - ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_ + ## * `align proc<#align,string,Natural,char>`_ + ## * `alignLeft proc<#alignLeft,string,Natural,char>`_ ## * `spaces proc<#spaces,Natural>`_ ## * `indent proc<#indent,string,Natural,string>`_ runnableExamples: @@ -1420,8 +1420,8 @@ proc indent*(s: string, count: Natural, padding: string = " "): string ## **Note:** This does not preserve the new line characters used in ``s``. ## ## See also: - ## * `align proc<#align,string,Natural,Char>`_ - ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_ + ## * `align proc<#align,string,Natural,char>`_ + ## * `alignLeft proc<#alignLeft,string,Natural,char>`_ ## * `spaces proc<#spaces,Natural>`_ ## * `unindent proc<#unindent,string,Natural,string>`_ runnableExamples: @@ -1445,8 +1445,8 @@ proc unindent*(s: string, count: Natural, padding: string = " "): string ## **Note:** This does not preserve the new line characters used in ``s``. ## ## See also: - ## * `align proc<#align,string,Natural,Char>`_ - ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_ + ## * `align proc<#align,string,Natural,char>`_ + ## * `alignLeft proc<#alignLeft,string,Natural,char>`_ ## * `spaces proc<#spaces,Natural>`_ ## * `indent proc<#indent,string,Natural,string>`_ runnableExamples: @@ -1471,8 +1471,8 @@ proc unindent*(s: string): string ## Removes all indentation composed of whitespace from each line in ``s``. ## ## See also: - ## * `align proc<#align,string,Natural,Char>`_ - ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_ + ## * `align proc<#align,string,Natural,char>`_ + ## * `alignLeft proc<#alignLeft,string,Natural,char>`_ ## * `spaces proc<#spaces,Natural>`_ ## * `indent proc<#indent,string,Natural,string>`_ runnableExamples: @@ -1862,7 +1862,7 @@ proc find*(s: string, sub: char, start: Natural = 0, last = 0): int {.noSideEffe ## Use `s[start..last].rfind` for a ``start``-origin index. ## ## See also: - ## * `rfind proc<#rfind,string,char,int,int>`_ + ## * `rfind proc<#rfind,string,char,Natural,int>`_ ## * `replace proc<#replace,string,char,char>`_ let last = if last == 0: s.high else: last when nimvm: @@ -1890,7 +1890,7 @@ proc find*(s: string, chars: set[char], start: Natural = 0, last = 0): int {.noS ## Use `s[start..last].find` for a ``start``-origin index. ## ## See also: - ## * `rfind proc<#rfind,string,set[char],int,int>`_ + ## * `rfind proc<#rfind,string,set[char],Natural,int>`_ ## * `multiReplace proc<#multiReplace,string,varargs[]>`_ let last = if last == 0: s.high else: last for i in int(start)..last: @@ -1907,7 +1907,7 @@ proc find*(s, sub: string, start: Natural = 0, last = 0): int {.noSideEffect, ## Use `s[start..last].find` for a ``start``-origin index. ## ## See also: - ## * `rfind proc<#rfind,string,string,int,int>`_ + ## * `rfind proc<#rfind,string,string,Natural,int>`_ ## * `replace proc<#replace,string,string,string>`_ if sub.len > s.len: return -1 if sub.len == 1: return find(s, sub[0], start, last) @@ -1927,7 +1927,7 @@ proc rfind*(s: string, sub: char, start: Natural = 0, last = -1): int {.noSideEf ## Use `s[start..last].find` for a ``start``-origin index. ## ## See also: - ## * `find proc<#find,string,char,int,int>`_ + ## * `find proc<#find,string,char,Natural,int>`_ let last = if last == -1: s.high else: last for i in countdown(last, start): if sub == s[i]: return i @@ -2101,7 +2101,8 @@ proc replace*(s: string, sub, by: char): string {.noSideEffect, rtl, extern: "nsuReplaceChar".} = ## Replaces `sub` in `s` by the character `by`. ## - ## Optimized version of `replace <#replace,string,string>`_ for characters. + ## Optimized version of `replace <#replace,string,string,string>`_ for + ## characters. ## ## See also: ## * `find proc<#find,string,char,Natural,int>`_ diff --git a/lib/std/sha1.nim b/lib/std/sha1.nim index 0099d5f6d..8f35a44ff 100644 --- a/lib/std/sha1.nim +++ b/lib/std/sha1.nim @@ -211,7 +211,7 @@ proc secureHashFile*(filename: string): SecureHash = ## Generates a ``SecureHash`` from a file. ## ## **See also:** - ## * `secureHash proc <#secureHash,string>`_ for generating a ``SecureHash`` from a string + ## * `secureHash proc <#secureHash,openArray[char]>`_ for generating a ``SecureHash`` from a string ## * `parseSecureHash proc <#parseSecureHash,string>`_ for converting a string ``hash`` to ``SecureHash`` secureHash(readFile(filename)) @@ -219,7 +219,7 @@ proc `$`*(self: SecureHash): string = ## Returns the string representation of a ``SecureHash``. ## ## **See also:** - ## * `secureHash proc <#secureHash,string>`_ for generating a ``SecureHash`` from a string + ## * `secureHash proc <#secureHash,openArray[char]>`_ for generating a ``SecureHash`` from a string runnableExamples: let hash = secureHash("Hello World") assert $hash == "0A4D55A8D778E5022FAB701977C5D840BBC486D0" @@ -231,7 +231,7 @@ proc parseSecureHash*(hash: string): SecureHash = ## Converts a string ``hash`` to ``SecureHash``. ## ## **See also:** - ## * `secureHash proc <#secureHash,string>`_ for generating a ``SecureHash`` from a string + ## * `secureHash proc <#secureHash,openArray[char]>`_ for generating a ``SecureHash`` from a string ## * `secureHashFile proc <#secureHashFile,string>`_ for generating a ``SecureHash`` from a file runnableExamples: let diff --git a/lib/system.nim b/lib/system.nim index 5e1bcd309..198c88e9b 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -112,8 +112,8 @@ proc defined*(x: untyped): bool {.magic: "Defined", noSideEffect, compileTime.} ## defined. ## ## `x` is an external symbol introduced through the compiler's - ## `-d:x switch <nimc.html#compile-time-symbols>`_ to enable build time - ## conditionals: + ## `-d:x switch <nimc.html#compiler-usage-compile-time-symbols>`_ to enable + ## build time conditionals: ## ## .. code-block:: Nim ## when not defined(release): @@ -784,7 +784,8 @@ type AssertionError* = object of Defect ## \ ## Raised when assertion is proved wrong. ## - ## Usually the result of using the `assert() template <#assert>`_. + ## Usually the result of using the `assert() template + ## <assertions.html#assert.t,untyped,string>`_. ValueError* = object of CatchableError ## \ ## Raised for string and object conversion errors. KeyError* = object of ValueError ## \ @@ -2017,8 +2018,8 @@ when defined(boehmgc): when taintMode: type TaintedString* = distinct string ## A distinct string type that ## is `tainted`:idx:, see `taint mode - ## <manual.html#taint-mode>`_ for - ## details. It is an alias for + ## <manual_experimental.html#taint-mode>`_ + ## for details. It is an alias for ## ``string`` if the taint mode is not ## turned on. @@ -2026,8 +2027,8 @@ when taintMode: else: type TaintedString* = string ## A distinct string type that ## is `tainted`:idx:, see `taint mode - ## <manual.html#taint-mode>`_ for - ## details. It is an alias for + ## <manual_experimental.html#taint-mode>`_ + ## for details. It is an alias for ## ``string`` if the taint mode is not ## turned on. @@ -2040,11 +2041,11 @@ else: const QuitSuccess* = 0 - ## is the value that should be passed to `quit <#quit>`_ to indicate + ## is the value that should be passed to `quit <#quit,int>`_ to indicate ## success. QuitFailure* = 1 - ## is the value that should be passed to `quit <#quit>`_ to indicate + ## is the value that should be passed to `quit <#quit,int>`_ to indicate ## failure. when defined(nodejs) and not defined(nimscript): @@ -3460,14 +3461,15 @@ when defined(nimvarargstyped): ## Unlike other IO operations this is guaranteed to be thread-safe as ## ``echo`` is very often used for debugging convenience. If you want to use ## ``echo`` inside a `proc without side effects - ## <manual.html#pragmas-noSideEffect-pragma>`_ you can use `debugEcho <#debugEcho>`_ - ## instead. + ## <manual.html#pragmas-nosideeffect-pragma>`_ you can use `debugEcho + ## <#debugEcho,varargs[typed,]>`_ instead. proc debugEcho*(x: varargs[typed, `$`]) {.magic: "Echo", noSideEffect, tags: [], raises: [].} - ## Same as `echo <#echo>`_, but as a special semantic rule, ``debugEcho`` - ## pretends to be free of side effects, so that it can be used for debugging - ## routines marked as `noSideEffect <manual.html#pragmas-noSideEffect-pragma>`_. + ## Same as `echo <#echo,varargs[typed,]>`_, but as a special semantic rule, + ## ``debugEcho`` pretends to be free of side effects, so that it can be used + ## for debugging routines marked as `noSideEffect + ## <manual.html#pragmas-nosideeffect-pragma>`_. else: proc echo*(x: varargs[untyped, `$`]) {.magic: "Echo", tags: [WriteIOEffect], benign, sideEffect.} @@ -4092,7 +4094,8 @@ proc staticExec*(command: string, input = "", cache = ""): string {. ## `gorge <#gorge,string,string,string>`_ is an alias for ``staticExec``. ## ## Note that you can use this proc inside a pragma like - ## `passc <nimc.html#passc-pragma>`_ or `passl <nimc.html#passl-pragma>`_. + ## `passc <manual.html#implementation-specific-pragmas-passc-pragma>`_ or + ## `passl <manual.html#implementation-specific-pragmas-passl-pragma>`_. ## ## If ``cache`` is not empty, the results of ``staticExec`` are cached within ## the ``nimcache`` directory. Use ``--forceBuild`` to get rid of this caching diff --git a/lib/system/assertions.nim b/lib/system/assertions.nim index 2131394e0..e0110d5c0 100644 --- a/lib/system/assertions.nim +++ b/lib/system/assertions.nim @@ -45,7 +45,7 @@ template assert*(cond: untyped, msg = "") = ## ## The compiler may not generate any code at all for ``assert`` if it is ## advised to do so through the ``-d:release`` or ``--assertions:off`` - ## `command line switches <nimc.html#command-line-switches>`_. + ## `command line switches <nimc.html#compiler-usage-command-line-switches>`_. const expr = astToStr(cond) assertImpl(cond, msg, expr, compileOption("assertions")) diff --git a/lib/system/nimscript.nim b/lib/system/nimscript.nim index 6f795d075..719e92c4a 100644 --- a/lib/system/nimscript.nim +++ b/lib/system/nimscript.nim @@ -311,9 +311,9 @@ proc cd*(dir: string) {.raises: [OSError].} = ## Changes the current directory. ## ## The change is permanent for the rest of the execution, since this is just - ## a shortcut for `os.setCurrentDir() - ## <http://nim-lang.org/docs/os.html#setCurrentDir,string>`_ . Use the `withDir() - ## <#withDir>`_ template if you want to perform a temporary change only. + ## a shortcut for `os.setCurrentDir() <os.html#setCurrentDir,string>`_ . Use + ## the `withDir() <#withDir.t,string,untyped>`_ template if you want to + ## perform a temporary change only. setCurrentDir(dir) checkOsError() @@ -326,7 +326,8 @@ proc findExe*(bin: string): string = template withDir*(dir: string; body: untyped): untyped = ## Changes the current directory temporarily. ## - ## If you need a permanent change, use the `cd() <#cd>`_ proc. Usage example: + ## If you need a permanent change, use the `cd() <#cd,string>`_ proc. + ## Usage example: ## ## .. code-block:: nim ## withDir "foo": |