jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix header inconsistencies in documentation (#11071)

Browse source
This commit is contained in:
Zed 2019-04-23 08:40:20 +02:00 • committed by Andreas Rumpf
commit 3b4952da94
17 changed files with 95 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

12
lib/impure/db_mysql.nim
View file

@ -14,7 +14,7 @@
## `db_postgres <db_postgres.html>`_. ## `db_postgres <db_postgres.html>`_.
## ##
## Parameter substitution ## Parameter substitution
## ---------------------- ## ======================
## ##
## All ``db_*`` modules support the same form of parameter substitution. ## All ``db_*`` modules support the same form of parameter substitution.
## That is, using the ``?`` (question mark) to signify the place where a ## That is, using the ``?`` (question mark) to signify the place where a
@ -25,10 +25,10 @@
## ##
## ##
## Examples ## Examples
## -------- ## ========
## ##
## Opening a connection to a database ## Opening a connection to a database
## ================================== ## ----------------------------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## import db_mysql ## import db_mysql
@ -36,7 +36,7 @@
## db.close() ## db.close()
## ##
## Creating a table ## Creating a table
## ================ ## ----------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"DROP TABLE IF EXISTS myTable") ## db.exec(sql"DROP TABLE IF EXISTS myTable")
@ -45,14 +45,14 @@
## name varchar(50) not null)""")) ## name varchar(50) not null)"""))
## ##
## Inserting data ## Inserting data
## ============== ## --------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)", ## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)",
## "Dominik") ## "Dominik")
## ##
## Larger example ## Larger example
## ============== ## --------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## ##

12
lib/impure/db_odbc.nim
View file

@ -20,7 +20,7 @@
## `db_mysql <db_mysql.html>`_. ## `db_mysql <db_mysql.html>`_.
## ##
## Parameter substitution ## Parameter substitution
## ---------------------- ## ======================
## ##
## All ``db_*`` modules support the same form of parameter substitution. ## All ``db_*`` modules support the same form of parameter substitution.
## That is, using the ``?`` (question mark) to signify the place where a ## That is, using the ``?`` (question mark) to signify the place where a
@ -31,10 +31,10 @@
## ##
## ##
## Examples ## Examples
## -------- ## ========
## ##
## Opening a connection to a database ## Opening a connection to a database
## ================================== ## ----------------------------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## import db_odbc ## import db_odbc
@ -42,7 +42,7 @@
## db.close() ## db.close()
## ##
## Creating a table ## Creating a table
## ================ ## ----------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"DROP TABLE IF EXISTS myTable") ## db.exec(sql"DROP TABLE IF EXISTS myTable")
@ -51,14 +51,14 @@
## name varchar(50) not null)""")) ## name varchar(50) not null)"""))
## ##
## Inserting data ## Inserting data
## ============== ## --------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)", ## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)",
## "Andreas") ## "Andreas")
## ##
## Large example ## Large example
## ============= ## -------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## ##

10
lib/impure/db_postgres.nim
View file

@ -14,7 +14,7 @@
## `db_mysql <db_mysql.html>`_. ## `db_mysql <db_mysql.html>`_.
## ##
## Parameter substitution ## Parameter substitution
## ---------------------- ## ======================
## ##
## All ``db_*`` modules support the same form of parameter substitution. ## All ``db_*`` modules support the same form of parameter substitution.
## That is, using the ``?`` (question mark) to signify the place where a ## That is, using the ``?`` (question mark) to signify the place where a
@ -38,10 +38,10 @@
## 3) ## 3)
## ##
## Examples ## Examples
## -------- ## ========
## ##
## Opening a connection to a database ## Opening a connection to a database
## ================================== ## ----------------------------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## import db_postgres ## import db_postgres
@ -49,7 +49,7 @@
## db.close() ## db.close()
## ##
## Creating a table ## Creating a table
## ================ ## ----------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"DROP TABLE IF EXISTS myTable") ## db.exec(sql"DROP TABLE IF EXISTS myTable")
@ -58,7 +58,7 @@
## name varchar(50) not null)""")) ## name varchar(50) not null)"""))
## ##
## Inserting data ## Inserting data
## ============== ## --------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)", ## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)",

12
lib/impure/db_sqlite.nim
View file

@ -14,7 +14,7 @@
## `db_mysql <db_mysql.html>`_. ## `db_mysql <db_mysql.html>`_.
## ##
## Parameter substitution ## Parameter substitution
## ---------------------- ## ======================
## ##
## All ``db_*`` modules support the same form of parameter substitution. ## All ``db_*`` modules support the same form of parameter substitution.
## That is, using the ``?`` (question mark) to signify the place where a ## That is, using the ``?`` (question mark) to signify the place where a
@ -24,10 +24,10 @@
## sql"INSERT INTO myTable (colA, colB, colC) VALUES (?, ?, ?)" ## sql"INSERT INTO myTable (colA, colB, colC) VALUES (?, ?, ?)"
## ##
## Examples ## Examples
## -------- ## ========
## ##
## Opening a connection to a database ## Opening a connection to a database
## ================================== ## ----------------------------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## import db_sqlite ## import db_sqlite
@ -35,7 +35,7 @@
## db.close() ## db.close()
## ##
## Creating a table ## Creating a table
## ================ ## ----------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"DROP TABLE IF EXISTS myTable") ## db.exec(sql"DROP TABLE IF EXISTS myTable")
@ -44,14 +44,14 @@
## name varchar(50) not null)""")) ## name varchar(50) not null)"""))
## ##
## Inserting data ## Inserting data
## ============== ## --------------
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)", ## db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)",
## "Jack") ## "Jack")
## ##
## Larger example ## Larger example
## ============== ## --------------
## ##
## .. code-block:: nim ## .. code-block:: nim
## ##

2
lib/js/asyncjs.nim
View file

@ -50,7 +50,7 @@
## proc loadGame(name: string): Future[Game] {.async.} ## proc loadGame(name: string): Future[Game] {.async.}
## ##
## JavaScript compatibility ## JavaScript compatibility
## ~~~~~~~~~~~~~~~~~~~~~~~~~ ## ========================
## ##
## Nim currently generates `async/await` JavaScript code which is supported in modern ## Nim currently generates `async/await` JavaScript code which is supported in modern
## EcmaScript and most modern versions of browsers, Node.js and Electron. ## EcmaScript and most modern versions of browsers, Node.js and Electron.

10
lib/pure/asyncdispatch.nim
View file

@ -65,7 +65,7 @@
## error), if there is no error however it returns the value of the future. ## error), if there is no error however it returns the value of the future.
## ##
## Asynchronous procedures ## Asynchronous procedures
## ----------------------- ## =======================
## ##
## Asynchronous procedures remove the pain of working with callbacks. They do ## Asynchronous procedures remove the pain of working with callbacks. They do
## this by allowing you to write asynchronous code the same way as you would ## this by allowing you to write asynchronous code the same way as you would
@ -99,7 +99,7 @@
## exceptions in async procs. ## exceptions in async procs.
## ##
## Handling Exceptions ## Handling Exceptions
## ~~~~~~~~~~~~~~~~~~~ ## -------------------
## ##
## The most reliable way to handle exceptions is to use ``yield`` on a future ## The most reliable way to handle exceptions is to use ``yield`` on a future
## then check the future's ``failed`` property. For example: ## then check the future's ``failed`` property. For example:
@ -125,7 +125,7 @@
## ##
## ##
## Discarding futures ## Discarding futures
## ------------------ ## ==================
## ##
## Futures should **never** be discarded. This is because they may contain ## Futures should **never** be discarded. This is because they may contain
## errors. If you do not care for the result of a Future then you should ## errors. If you do not care for the result of a Future then you should
@ -134,14 +134,14 @@
## ``waitFor`` for that purpose. ## ``waitFor`` for that purpose.
## ##
## Examples ## Examples
## -------- ## ========
## ##
## For examples take a look at the documentation for the modules implementing ## For examples take a look at the documentation for the modules implementing
## asynchronous IO. A good place to start is the ## asynchronous IO. A good place to start is the
## `asyncnet module <asyncnet.html>`_. ## `asyncnet module <asyncnet.html>`_.
## ##
## Limitations/Bugs ## Limitations/Bugs
## ---------------- ## ================
## ##
## * The effect system (``raises: []``) does not work with async procedures. ## * The effect system (``raises: []``) does not work with async procedures.

6
lib/pure/asyncftpclient.nim
View file

@ -16,7 +16,7 @@
## * Navigation through the FTP server's directories. ## * Navigation through the FTP server's directories.
## ##
## Connecting to an FTP server ## Connecting to an FTP server
## ------------------------ ## ===========================
## ##
## In order to begin any sort of transfer of files you must first ## In order to begin any sort of transfer of files you must first
## connect to an FTP server. You can do so with the ``connect`` procedure. ## connect to an FTP server. You can do so with the ``connect`` procedure.
@ -34,7 +34,7 @@
## client will be connected after the ``await ftp.connect()`` call. ## client will be connected after the ``await ftp.connect()`` call.
## ##
## Uploading a new file ## Uploading a new file
## -------------------- ## ====================
## ##
## After a connection is made you can use the ``store`` procedure to upload ## After a connection is made you can use the ``store`` procedure to upload
## a new file to the FTP server. Make sure to check you are in the correct ## a new file to the FTP server. Make sure to check you are in the correct
@ -53,7 +53,7 @@
## waitFor(main()) ## waitFor(main())
## ##
## Checking the progress of a file transfer ## Checking the progress of a file transfer
## ---------------------------------------- ## ========================================
## ##
## The progress of either a file upload or a file download can be checked ## The progress of either a file upload or a file download can be checked
## by specifying a ``onProgressChanged`` procedure to the ``store`` or ## by specifying a ``onProgressChanged`` procedure to the ``store`` or

3
lib/pure/asynchttpserver.nim
View file

@ -14,9 +14,8 @@
## application you should use a reverse proxy (for example nginx) instead of ## application you should use a reverse proxy (for example nginx) instead of
## allowing users to connect directly to this server. ## allowing users to connect directly to this server.
## ##
##
## Basic usage ## Basic usage
## ----------- ## ===========
## ##
## This example will create an HTTP server on port 8080. The server will ## This example will create an HTTP server on port 8080. The server will
## respond to all requests with a ``200 OK`` response code and "Hello World" ## respond to all requests with a ``200 OK`` response code and "Hello World"

2
lib/pure/asyncmacro.nim
View file

@ -7,8 +7,6 @@
# distribution, for details about the copyright. # distribution, for details about the copyright.
# #
## AsyncMacro
## *************
## `asyncdispatch` module depends on the `asyncmacro` module to work properly. ## `asyncdispatch` module depends on the `asyncmacro` module to work properly.
import macros, strutils, asyncfutures import macros, strutils, asyncfutures

8
lib/pure/asyncnet.nim
View file

@ -11,7 +11,7 @@
## asynchronous dispatcher defined in the ``asyncdispatch`` module. ## asynchronous dispatcher defined in the ``asyncdispatch`` module.
## ##
## Asynchronous IO in Nim ## Asynchronous IO in Nim
## ---------------------- ## ======================
## ##
## Async IO in Nim consists of multiple layers (from highest to lowest): ## Async IO in Nim consists of multiple layers (from highest to lowest):
## ##
@ -49,7 +49,7 @@
## over all the layers, providing some extra features such as buffering. ## over all the layers, providing some extra features such as buffering.
## ##
## SSL ## SSL
## ---- ## ===
## ##
## SSL can be enabled by compiling with the ``-d:ssl`` flag. ## SSL can be enabled by compiling with the ``-d:ssl`` flag.
## ##
@ -58,10 +58,10 @@
## the newly created SSL context to get an SSL socket. ## the newly created SSL context to get an SSL socket.
## ##
## Examples ## Examples
## -------- ## ========
## ##
## Chat server ## Chat server
## ^^^^^^^^^^^ ## -----------
## ##
## The following example demonstrates a simple chat server. ## The following example demonstrates a simple chat server.
## ##

1
lib/pure/base64.nim
View file

@ -15,7 +15,6 @@
## bytes (i.e., a total of 24 bits) can therefore be represented by ## bytes (i.e., a total of 24 bits) can therefore be represented by
## four 6-bit Base64 digits. ## four 6-bit Base64 digits.
## ##
##
## Basic usage ## Basic usage
## =========== ## ===========
## ##

4
lib/pure/dynlib.nim
View file

@ -12,10 +12,10 @@
## Windows ``LoadLibrary``. ## Windows ``LoadLibrary``.
## ##
## Examples ## Examples
## -------- ## ========
## ##
## Loading a simple C function ## Loading a simple C function
## ^^^^^^^^^^^^^^^^^^^^^^^^^^^ ## ---------------------------
## ##
## The following example demonstrates loading a function called 'greet' ## The following example demonstrates loading a function called 'greet'
## from a library that is determined at runtime based upon a language choice. ## from a library that is determined at runtime based upon a language choice.

3
lib/pure/htmlgen.nim
View file

@ -16,7 +16,8 @@
## generator. Each commonly used HTML tag has a corresponding macro ## generator. Each commonly used HTML tag has a corresponding macro
## that generates a string with its HTML representation. ## that generates a string with its HTML representation.
## ##
## Example: ## Examples
## ========
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## var nim = "Nim" ## var nim = "Nim"

84
lib/pure/parsecfg.nim
View file

@ -12,48 +12,46 @@
## format, but much more powerful, as it is not a line based parser. String ## format, but much more powerful, as it is not a line based parser. String
## literals, raw string literals and triple quoted string literals are supported ## literals, raw string literals and triple quoted string literals are supported
## as in the Nim programming language. ## as in the Nim programming language.
##
## This is an example of how a configuration file may look like: ## Example of how a configuration file may look like:
## ##
## .. include:: ../../doc/mytest.cfg ## .. include:: ../../doc/mytest.cfg
## :literal: ## :literal:
## ##
## Here is an example of how to use the configuration file parser:
##[ Here is an example of how to use the configuration file parser: ##
## .. code-block:: nim
.. code-block:: nim ##
## import os, parsecfg, strutils, streams
import ##
os, parsecfg, strutils, streams ## var f = newFileStream(paramStr(1), fmRead)
## if f != nil:
var f = newFileStream(paramStr(1), fmRead) ## var p: CfgParser
if f != nil: ## open(p, f, paramStr(1))
var p: CfgParser ## while true:
open(p, f, paramStr(1)) ## var e = next(p)
while true: ## case e.kind
var e = next(p) ## of cfgEof: break
case e.kind ## of cfgSectionStart: ## a ``[section]`` has been parsed
of cfgEof: break ## echo("new section: " & e.section)
of cfgSectionStart: ## a ``[section]`` has been parsed ## of cfgKeyValuePair:
echo("new section: " & e.section) ## echo("key-value-pair: " & e.key & ": " & e.value)
of cfgKeyValuePair: ## of cfgOption:
echo("key-value-pair: " & e.key & ": " & e.value) ## echo("command: " & e.key & ": " & e.value)
of cfgOption: ## of cfgError:
echo("command: " & e.key & ": " & e.value) ## echo(e.msg)
of cfgError: ## close(p)
echo(e.msg) ## else:
close(p) ## echo("cannot open: " & paramStr(1))
else: ##
echo("cannot open: " & paramStr(1)) ##
]##
## Examples ## Examples
## -------- ## ========
## ##
## This is an example of a configuration file. ## Configuration file example
## --------------------------
## ##
## :: ## .. code-block:: nim
## ##
## charset = "utf-8" ## charset = "utf-8"
## [Package] ## [Package]
@ -64,8 +62,8 @@
## qq = "10214028" ## qq = "10214028"
## email = "lihaifeng@wxm.com" ## email = "lihaifeng@wxm.com"
## ##
## Creating a configuration file. ## Creating a configuration file
## ============================== ## -----------------------------
## .. code-block:: nim ## .. code-block:: nim
## ##
## import parsecfg ## import parsecfg
@ -78,8 +76,8 @@
## dict.setSectionKey("Author","email","lihaifeng@wxm.com") ## dict.setSectionKey("Author","email","lihaifeng@wxm.com")
## dict.writeConfig("config.ini") ## dict.writeConfig("config.ini")
## ##
## Reading a configuration file. ## Reading a configuration file
## ============================= ## ----------------------------
## .. code-block:: nim ## .. code-block:: nim
## ##
## import parsecfg ## import parsecfg
@ -92,8 +90,8 @@
## var email = dict.getSectionValue("Author","email") ## var email = dict.getSectionValue("Author","email")
## echo pname & "\n" & name & "\n" & qq & "\n" & email ## echo pname & "\n" & name & "\n" & qq & "\n" & email
## ##
## Modifying a configuration file. ## Modifying a configuration file
## =============================== ## ------------------------------
## .. code-block:: nim ## .. code-block:: nim
## ##
## import parsecfg ## import parsecfg
@ -101,8 +99,8 @@
## dict.setSectionKey("Author","name","lhf") ## dict.setSectionKey("Author","name","lhf")
## dict.writeConfig("config.ini") ## dict.writeConfig("config.ini")
## ##
## Deleting a section key in a configuration file. ## Deleting a section key in a configuration file
## =============================================== ## ----------------------------------------------
## .. code-block:: nim ## .. code-block:: nim
## ##
## import parsecfg ## import parsecfg

13
lib/pure/times.nim
View file

@ -17,7 +17,8 @@
resolution used by ``getTime()`` depends on the platform and backend resolution used by ``getTime()`` depends on the platform and backend
(JS is limited to millisecond precision). (JS is limited to millisecond precision).
Examples: Examples
========
.. code-block:: nim .. code-block:: nim
import times, os import times, os
@ -38,7 +39,7 @@
echo "One month from now : ", now() + 1.months echo "One month from now : ", now() + 1.months
Parsing and Formatting Dates Parsing and Formatting Dates
---------------------------- ============================
The ``DateTime`` type can be parsed and formatted using the different The ``DateTime`` type can be parsed and formatted using the different
``parse`` and ``format`` procedures. ``parse`` and ``format`` procedures.
@ -128,7 +129,7 @@
only for years in the range 1..9999). only for years in the range 1..9999).
Duration vs TimeInterval Duration vs TimeInterval
---------------------------- ============================
The ``times`` module exports two similiar types that are both used to The ``times`` module exports two similiar types that are both used to
represent some amount of time: `Duration <#Duration>`_ and represent some amount of time: `Duration <#Duration>`_ and
`TimeInterval <#TimeInterval>`_. `TimeInterval <#TimeInterval>`_.
@ -137,7 +138,7 @@
needed). needed).
Duration Duration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
A ``Duration`` represents a duration of time stored as seconds and A ``Duration`` represents a duration of time stored as seconds and
nanoseconds. A ``Duration`` is always fully normalized, so nanoseconds. A ``Duration`` is always fully normalized, so
``initDuration(hours = 1)`` and ``initDuration(minutes = 60)`` are equivilant. ``initDuration(hours = 1)`` and ``initDuration(minutes = 60)`` are equivilant.
@ -147,7 +148,7 @@
is more performant and easier to understand it should generally prefered. is more performant and easier to understand it should generally prefered.
TimeInterval TimeInterval
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
A ``TimeInterval`` represents some amount of time expressed in calendar A ``TimeInterval`` represents some amount of time expressed in calendar
units, for example "1 year and 2 days". Since some units cannot be units, for example "1 year and 2 days". Since some units cannot be
normalized (the length of a year is different for leap years for example), normalized (the length of a year is different for leap years for example),
@ -164,7 +165,7 @@
``Duration`` doesn't have. ``Duration`` doesn't have.
How long is a day? How long is a day?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
It should be especially noted that the handling of days differs between It should be especially noted that the handling of days differs between
``TimeInterval`` and ``Duration``. The ``Duration`` type always treats a day ``TimeInterval`` and ``Duration``. The ``Duration`` type always treats a day
as exactly 86400 seconds. For ``TimeInterval``, it's more complex. as exactly 86400 seconds. For ``TimeInterval``, it's more complex.

4
lib/pure/unittest.nim
View file

@ -57,8 +57,8 @@
## # Run suites starting with 'bug #' and standalone tests starting with '#' ## # Run suites starting with 'bug #' and standalone tests starting with '#'
## nim c -r test 'bug #*::' '::#*' ## nim c -r test 'bug #*::' '::#*'
## ##
## Example ## Examples
## ------- ## ========
## ##
## .. code:: nim ## .. code:: nim
## ##

5
lib/system/threads.nim
View file

@ -19,7 +19,8 @@
## to prevent race conditions and improves efficiency. See `the manual for ## to prevent race conditions and improves efficiency. See `the manual for
## details of this memory model <manual.html#threads>`_. ## details of this memory model <manual.html#threads>`_.
## ##
## Example: ## Examples
## ========
## ##
## .. code-block:: Nim ## .. code-block:: Nim
## ##
@ -328,7 +329,7 @@ else:
proc createThread*(t: var Thread[void], tp: proc () {.thread, nimcall.}) = proc createThread*(t: var Thread[void], tp: proc () {.thread, nimcall.}) =
createThread[void](t, tp) createThread[void](t, tp)
## we need to cache current threadId to not perform syscall all the time # we need to cache current threadId to not perform syscall all the time
var threadId {.threadvar.}: int var threadId {.threadvar.}: int
when defined(windows): when defined(windows):