Massive documentation fixes + copy editing (nim-lang#15747)

doc/apis.rst

@@ -3,7 +3,7 @@ API naming design
 =================
 
 The API is designed to be **easy to use** and consistent. Ease of use is
-measured by the number of calls to achieve a concrete high level action.
+measured by the number of calls to achieve a concrete high-level action.
 
 
 Naming scheme

doc/backends.rst

@@ -15,16 +15,16 @@ Introduction
 The `Nim Compiler User Guide <nimc.html>`_ documents the typical
 compiler invocation, using the ``compile`` or ``c`` command to transform a
 ``.nim`` file into one or more ``.c`` files which are then compiled with the
-platform's C compiler into a static binary. However there are other commands
-to compile to C++, Objective-C or JavaScript. This document tries to
+platform's C compiler into a static binary. However, there are other commands
+to compile to C++, Objective-C, or JavaScript. This document tries to
 concentrate in a single place all the backend and interfacing options.
 
 The Nim compiler supports mainly two backend families: the C, C++ and
 Objective-C targets and the JavaScript target. `The C like targets
-<#backends-the-c-like-targets>`_ creates source files which can be compiled
+<#backends-the-c-like-targets>`_ creates source files that can be compiled
 into a library or a final executable. `The JavaScript target
 <#backends-the-javascript-target>`_ can generate a ``.js`` file which you
-reference from an HTML file or create a `standalone nodejs program
+reference from an HTML file or create a `standalone Node.js program
 <http://nodejs.org>`_.
 
 On top of generating libraries or standalone applications, Nim offers
@@ -48,16 +48,16 @@ The most significant difference between these commands is that if you look
 into the ``nimcache`` directory you will find ``.c``, ``.cpp`` or ``.m``
 files, other than that all of them will produce a native binary for your
 project.  This allows you to take the generated code and place it directly
-into a project using any of these languages. Here are some typical command
+into a project using any of these languages. Here are some typical command-
 line invocations::
 
     $ nim c hallo.nim
     $ nim cpp hallo.nim
     $ nim objc hallo.nim
 
 The compiler commands select the target backend, but if needed you can
-`specify additional switches for cross compilation
-<nimc.html#cross-compilation>`_ to select the target CPU, operative system
+`specify additional switches for cross-compilation
+<nimc.html#crossminuscompilation>`_ to select the target CPU, operative system
 or compiler/linker commands.
 
 
@@ -79,7 +79,7 @@ available. This includes:
 * OS-specific operations
 * threading, coroutines
 * some modules of the standard library
-* proper 64 bit integer arithmetic
+* proper 64-bit integer arithmetic
 
 To compensate, the standard library has modules `catered to the JS backend
 <lib.html#pure-libraries-modules-for-js-backend>`_
@@ -119,7 +119,7 @@ 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
-same html file which hosts the generated JavaScript will likely provide other
+same HTML file which hosts the generated JavaScript will likely provide other
 JavaScript functions which you are importing with ``importc``.
 
 However, for the C like targets you need to link external code either
@@ -167,7 +167,7 @@ With these two files in place, you can run ``nim c -r calculator.nim`` and
 the Nim compiler will compile the ``logic.c`` file in addition to
 ``calculator.nim`` and link both into an executable, which outputs ``10`` when
 run. Another way to link the C file statically and get the same effect would
-be remove the line with the ``compile`` pragma and run the following typical
+be to remove the line with the ``compile`` pragma and run the following typical
 Unix commands::
 
     $ gcc -c logic.c
@@ -211,7 +211,7 @@ calculator.nim`` and open ``host.html`` in a browser. If the browser supports
 javascript, you should see the value ``10`` in the browser's console. Use the
 `dom module <dom.html>`_ for specific DOM querying and modification procs
 or take a look at `karax <https://github.com/pragmagic/karax>`_ for how to
-develop browser based applications.
+develop browser-based applications.
 
 
 Backend code calling Nim
@@ -220,7 +220,7 @@ Backend code calling Nim
 Backend code can interface with Nim code exposed through the `exportc
 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
+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.
@@ -233,7 +233,7 @@ the compiler will assume certain types for the return value and parameters
 which will likely make your program crash at runtime.
 
 The Nim compiler can generate a C interface header through the ``--header``
-command line switch. The generated header will contain all the exported
+command-line switch. The generated header will contain all the exported
 symbols and the ``NimMain`` proc which you need to call before any other
 Nim code.
 
@@ -322,8 +322,8 @@ from the previous section):
 Compile the Nim code to JavaScript with ``nim js -o:fib.js fib.nim`` and
 open ``mhost.html`` in a browser. If the browser supports javascript, you
 should see an alert box displaying the text ``Fib for 9 is 34``. As mentioned
-earlier, JavaScript doesn't require an initialisation call to ``NimMain`` or
-similar function and you can call the exported Nim proc directly.
+earlier, JavaScript doesn't require an initialization call to ``NimMain`` or
+a similar function and you can call the exported Nim proc directly.
 
 
 Nimcache naming logic
@@ -333,15 +333,15 @@ 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#compiler-usage-command-line-switches>`_ to change it.
+<nimc.html#compiler-usage-commandminusline-switches>`_ to change it.
 
 
 Memory management
 =================
 
-In the previous sections the ``NimMain()`` function reared its head. Since
+In the previous sections, the ``NimMain()`` function reared its head. Since
 JavaScript already provides automatic memory management, you can freely pass
-objects between the two language without problems. In C and derivate languages
+objects between the two languages without problems. In C and derivate languages
 you need to be careful about what you do and how you share memory. The
 previous examples only dealt with simple scalar values, but passing a Nim
 string to C, or reading back a C string in Nim already requires you to be
@@ -355,7 +355,7 @@ The manual mentions that `Nim strings are implicitly convertible to
 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
+they return the string won't be needed anymore. 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,string>`_ and `GC_unref
@@ -388,7 +388,7 @@ to hand a Nim reference to C code, you will need to use `GC_ref
 <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,ref.T>`_ proc to clean up this memory when it is not
-required any more.
+required anymore.
 
 Again, if you are wrapping a library which *mallocs* and *frees* data
 structures, you need to expose the appropriate *free* function to Nim so
@@ -424,4 +424,3 @@ leaks by calling
 .. code-block:: nim
 
   system.tearDownForeignThreadGc()
-

doc/destructors.rst

@@ -25,7 +25,7 @@ move semantics and destructors work in Nim.
 Motivating example
 ==================
 
-With the language mechanisms described here a custom seq could be
+With the language mechanisms described here, a custom seq could be
 written as:
 
 .. code-block:: nim
@@ -88,7 +88,7 @@ Lifetime-tracking hooks
 =======================
 
 The memory management for Nim's standard ``string`` and ``seq`` types as
-well as other standard collections is performed via so called
+well as other standard collections is performed via so-called
 "Lifetime-tracking hooks" or "type-bound operators". There are 3 different
 hooks for each (generic or concrete) object type ``T`` (``T`` can also be a
 ``distinct`` type) that are called implicitly by the compiler.
@@ -128,13 +128,13 @@ The general pattern in ``=destroy`` looks like:
 ------------
 
 A `=sink` hook moves an object around, the resources are stolen from the source
-and passed to the destination. It is ensured that source's destructor does
-not free the resources afterwards by setting the object to its default value
+and passed to the destination. It is ensured that the source's destructor does
+not free the resources afterward by setting the object to its default value
 (the value the object's state started in). Setting an object ``x`` back to its
 default value is written as ``wasMoved(x)``. When not provided the compiler
 is using a combination of `=destroy` and `copyMem` instead. This is efficient
 hence users rarely need to implement their own `=sink` operator, it is enough to
-provide `=destroy` and `=copy`, compiler will take care about the rest.
+provide `=destroy` and `=copy`, compiler will take care of the rest.
 
 The prototype of this hook for a type ``T`` needs to be:
 
@@ -191,7 +191,7 @@ Move semantics
 ==============
 
 A "move" can be regarded as an optimized copy operation. If the source of the
-copy operation is not used afterwards, the copy can be replaced by a move. This
+copy operation is not used afterward, the copy can be replaced by a move. This
 document uses the notation ``lastReadOf(x)`` to describe that ``x`` is not
 used afterwards. This property is computed by a static control flow analysis
 but can also be enforced by using ``system.move`` explicitly.
@@ -218,7 +218,7 @@ Sink parameters
 ===============
 
 To move a variable into a collection usually ``sink`` parameters are involved.
-A location that is passed to a ``sink`` parameter should not be used afterwards.
+A location that is passed to a ``sink`` parameter should not be used afterward.
 This is ensured by a static analysis over a control flow graph. If it cannot be
 proven to be the last usage of the location, a copy is done instead and this
 copy is then passed to the sink parameter.
@@ -232,7 +232,7 @@ without any further overloads and ``put`` might not take ownership of ``k`` if
 not a linear type system.
 
 The employed static analysis is limited and only concerned with local variables;
-however object and tuple fields are treated as separate entities:
+however, object and tuple fields are treated as separate entities:
 
 .. code-block:: nim
 
@@ -509,7 +509,7 @@ to avoid this overhead:
 In fact, ``.cursor`` more generally prevents object construction/destruction pairs
 and so can also be useful in other contexts. The alternative solution would be to
 use raw pointers (``ptr``) instead which is more cumbersome and also more dangerous
-for Nim's evolution: Later on the compiler can try to prove ``.cursor`` annotations
+for Nim's evolution: Later on, the compiler can try to prove ``.cursor`` annotations
 to be safe, but for ``ptr`` the compiler has to remain silent about possible
 problems.
 
@@ -522,7 +522,7 @@ a form of copy elision.
 
 To see how and when we can do that, think about this question: In `dest = src` when
 do we really have to *materialize* the full copy? - Only if `dest` or `src` are mutated
-afterwards. If `dest` is a local variable that is simple to analyse. And if `src` is a
+afterward. If `dest` is a local variable that is simple to analyze. And if `src` is a
 location derived from a formal parameter, we also know it is not mutated! In other
 words, we do a compile-time copy-on-write analysis.
 
@@ -547,9 +547,9 @@ other words, a copy ``x = y`` is implemented
 as ``x[0] = y[0]; x[1] = y[1]; ...``, likewise for ``=sink`` and ``=destroy``.
 
 Other value-based compound types like ``object`` and ``array`` are handled
-correspondingly. For ``object`` however, the compiler generated hooks
+correspondingly. For ``object`` however, the compiler-generated hooks
 can be overridden. This can also be important to use an alternative traversal
-of the involved datastructure that is more efficient or in order to avoid
+of the involved data structure that is more efficient or in order to avoid
 deep recursions.