Documentation renames

This commit is contained in:
def 2015-01-16 00:22:49 +01:00
commit 110c4aca7f
8 changed files with 80 additions and 80 deletions

View file

@ -31,13 +31,13 @@ documentation with only their well-documented code.
Example: Example:
.. code-block:: nim .. code-block:: nim
type TPerson* = object type Person* = object
## This type contains a description of a person ## This type contains a description of a person
name: string name: string
age: int age: int
Outputs:: Outputs::
TPerson* = object Person* = object
name: string name: string
age: int age: int
@ -268,8 +268,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 ``compiler/docgen.nim`` file. Here are some examples of complex names for
symbols in the `system module <system.html>`_. symbols in the `system module <system.html>`_.
* ``type TSignedInt = int | int8 | int16 | int32 | int64`` **=>** * ``type SignedInt = int | int8 | int16 | int32 | int64`` **=>**
`#TSignedInt <system.html#TSignedInt>`_ `#SignedInt <system.html#SignedInt>`_
* ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>** * ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>**
`#globalRaiseHook <system.html#globalRaiseHook>`_ `#globalRaiseHook <system.html#globalRaiseHook>`_
* ``const NimVersion = "0.0.0"`` **=>** * ``const NimVersion = "0.0.0"`` **=>**
@ -307,7 +307,7 @@ columns is:
Nim's rules (eg. \`^\` like in `the actors module Nim's rules (eg. \`^\` like in `the actors module
<actors.html#^,ptr.TChannel[T]>`_). <actors.html#^,ptr.TChannel[T]>`_).
2. Base filename plus anchor hyper link (eg. 2. Base filename plus anchor hyper link (eg.
``algorithm.html#*,int,TSortOrder``). ``algorithm.html#*,int,SortOrder``).
3. Optional human readable string to display as hyper link. If the value is not 3. Optional human readable string to display as hyper link. If the value is not
present or is the empty string, the hyper link will be rendered present or is the empty string, the hyper link will be rendered
using the term. Prefix whitespace indicates that this entry is using the term. Prefix whitespace indicates that this entry is

View file

@ -173,7 +173,7 @@ The template engine is quite flexible. It is easy to produce a procedure that
writes the template code directly to a file:: writes the template code directly to a file::
#! stdtmpl(emit="f.write") | standard #! stdtmpl(emit="f.write") | standard
#proc writeHTMLPage(f: TFile, title, currentTab, content: string, #proc writeHTMLPage(f: File, title, currentTab, content: string,
# tabs: openArray[string]) = # tabs: openArray[string]) =
<head><title>$title</title></head> <head><title>$title</title></head>
<body> <body>

View file

@ -213,7 +213,7 @@ tab characters (``\t``). The values of each column are:
``proj.symbolName``. ``proj.symbolName``.
4. Type/signature. For variables and enums this will contain the 4. Type/signature. For variables and enums this will contain the
type of the symbol, for procs, methods and templates this will type of the symbol, for procs, methods and templates this will
contain the full unique signature (e.g. ``proc (TFile)``). contain the full unique signature (e.g. ``proc (File)``).
5. Full path to the file containing the symbol. 5. Full path to the file containing the symbol.
6. Line where the symbol is located in the file. Lines start to 6. Line where the symbol is located in the file. Lines start to
count at **1**. count at **1**.
@ -258,8 +258,8 @@ skEnumField
.. code-block:: nim .. code-block:: nim
Open(filename, fmWrite) Open(filename, fmWrite)
--> col 2: system.TFileMode.fmWrite --> col 2: system.FileMode.fmWrite
col 3: TFileMode col 3: FileMode
col 7: "" col 7: ""
@ -296,7 +296,7 @@ posterior instances of the iterator.
text = "some text" text = "some text"
letters = toSeq(runes(text)) letters = toSeq(runes(text))
--> col 2: unicode.runes --> col 2: unicode.runes
col 3: iterator (string): TRune col 3: iterator (string): Rune
col 7: "iterates over any unicode character of the string `s`." col 7: "iterates over any unicode character of the string `s`."
@ -423,7 +423,7 @@ returned by idetools returns also the pragmas for the proc.
.. code-block:: nim .. code-block:: nim
Open(filename, fmWrite) Open(filename, fmWrite)
--> col 2: system.Open --> col 2: system.Open
col 3: proc (var TFile, string, TFileMode, int): bool col 3: proc (var File, string, FileMode, int): bool
col 7: col 7:
"Opens a file named `filename` with given `mode`. "Opens a file named `filename` with given `mode`.
@ -487,9 +487,9 @@ skType
.. code-block:: nim .. code-block:: nim
proc writeTempFile() = proc writeTempFile() =
var output: TFile var output: File
--> col 2: system.TFile --> col 2: system.File
col 3: TFile col 3: File
col 7: "" col 7: ""
@ -502,11 +502,11 @@ skVar
.. code-block:: nim .. code-block:: nim
proc writeTempFile() = proc writeTempFile() =
var output: TFile var output: File
output.open("/tmp/somefile", fmWrite) output.open("/tmp/somefile", fmWrite)
output.write("test") output.write("test")
--> col 2: $MODULE.writeTempFile.output --> col 2: $MODULE.writeTempFile.output
col 3: TFile col 3: File
col 7: "" col 7: ""

View file

@ -311,8 +311,8 @@ underlying C ``struct`` in a ``sizeof`` expression:
.. code-block:: Nim .. code-block:: Nim
type type
TDIR* {.importc: "DIR", header: "<dirent.h>", DIR* {.importc: "DIR", header: "<dirent.h>",
final, pure, incompleteStruct.} = object final, pure, incompleteStruct.} = object
Compile pragma Compile pragma
@ -418,8 +418,8 @@ interfacing with libraries written in C++:
irr = "<irrlicht/irrlicht.h>" irr = "<irrlicht/irrlicht.h>"
type type
TIrrlichtDevice {.final, header: irr, importc: "IrrlichtDevice".} = object IrrlichtDeviceObj {.final, header: irr, importc: "IrrlichtDevice".} = object
PIrrlichtDevice = ptr TIrrlichtDevice IrrlichtDevice = ptr IrrlichtDeviceObj
proc createDevice(): PIrrlichtDevice {. proc createDevice(): PIrrlichtDevice {.
header: irr, importc: "createDevice".} header: irr, importc: "createDevice".}
@ -465,11 +465,11 @@ allows *sloppy* interfacing with libraries written in Objective C:
""".} """.}
type type
TId {.importc: "id", header: "<objc/Object.h>", final.} = distinct int Id {.importc: "id", header: "<objc/Object.h>", final.} = distinct int
proc newGreeter: TId {.importobjc: "Greeter new", nodecl.} proc newGreeter: Id {.importobjc: "Greeter new", nodecl.}
proc greet(self: TId, x, y: int) {.importobjc: "greet", nodecl.} proc greet(self: Id, x, y: int) {.importobjc: "greet", nodecl.}
proc free(self: TId) {.importobjc: "free", nodecl.} proc free(self: Id) {.importobjc: "free", nodecl.}
var g = newGreeter() var g = newGreeter()
g.greet(12, 34) g.greet(12, 34)

View file

@ -213,7 +213,7 @@ example ``*`` should not be greedy, so ``\[.*?\]`` should be used instead.
PEG construction PEG construction
---------------- ----------------
There are two ways to construct a PEG in Nim code: There are two ways to construct a PEG in Nim code:
(1) Parsing a string into an AST which consists of `TPeg` nodes with the (1) Parsing a string into an AST which consists of `Peg` nodes with the
`peg` proc. `peg` proc.
(2) Constructing the AST directly with proc calls. This method does not (2) Constructing the AST directly with proc calls. This method does not
support constructing rules, only simple expressions and is not as support constructing rules, only simple expressions and is not as

View file

@ -8,9 +8,9 @@ can also be used to include elements (and ranges of elements):
.. code-block:: nim .. code-block:: nim
type type
TCharSet = set[char] CharSet = set[char]
var var
x: TCharSet x: CharSet
x = {'a'..'z', '0'..'9'} # This constructs a set that contains the x = {'a'..'z', '0'..'9'} # This constructs a set that contains the
# letters from 'a' to 'z' and the digits # letters from 'a' to 'z' and the digits
# from '0' to '9' # from '0' to '9'

View file

@ -1350,11 +1350,11 @@ integer.
.. code-block:: nim .. code-block:: nim
type type
TPerson = tuple[name: string, age: int] # type representing a person: Person = tuple[name: string, age: int] # type representing a person:
# a person consists of a name # a person consists of a name
# and an age # and an age
var var
person: TPerson person: Person
person = (name: "Peter", age: 30) person = (name: "Peter", age: 30)
# the same, but less readable: # the same, but less readable:
person = ("Peter", 30) person = ("Peter", 30)
@ -1373,7 +1373,7 @@ integer.
# The following line does not compile, they are different tuples! # The following line does not compile, they are different tuples!
#person = building #person = building
# --> Error: type mismatch: got (tuple[street: string, number: int]) # --> Error: type mismatch: got (tuple[street: string, number: int])
# but expected 'TPerson' # but expected 'Person'
# The following works because the field names and types are the same. # The following works because the field names and types are the same.
var teacher: tuple[name: string, age: int] = ("Mark", 42) var teacher: tuple[name: string, age: int] = ("Mark", 42)

View file

@ -56,19 +56,19 @@ Objects have access to their type at runtime. There is an
.. code-block:: nim .. code-block:: nim
type type
TPerson = object of RootObj Person = object of RootObj
name*: string # the * means that `name` is accessible from other modules name*: string # the * means that `name` is accessible from other modules
age: int # no * means that the field is hidden from other modules age: int # no * means that the field is hidden from other modules
TStudent = object of TPerson # TStudent inherits from TPerson Student = object of Person # Student inherits from Person
id: int # with an id field id: int # with an id field
var var
student: TStudent student: Student
person: TPerson person: Person
assert(student of TStudent) # is true assert(student of Student) # is true
# object construction: # object construction:
student = TStudent(name: "Anton", age: 5, id: 2) student = Student(name: "Anton", age: 5, id: 2)
Object fields that should be visible from outside the defining module have to Object fields that should be visible from outside the defining module have to
be marked by ``*``. In contrast to tuples, different object types are be marked by ``*``. In contrast to tuples, different object types are
@ -100,15 +100,15 @@ Example:
.. code-block:: nim .. code-block:: nim
type type
PNode = ref TNode # a traced reference to a TNode Node = ref NodeObj # a traced reference to a NodeObj
TNode = object NodeObj = object
le, ri: PNode # left and right subtrees le, ri: Node # left and right subtrees
sym: ref TSym # leaves contain a reference to a TSym sym: ref Sym # leaves contain a reference to a Sym
TSym = object # a symbol Sym = object # a symbol
name: string # the symbol's name name: string # the symbol's name
line: int # the line the symbol was declared in line: int # the line the symbol was declared in
code: PNode # the symbol's abstract syntax tree code: PNode # the symbol's abstract syntax tree
Type conversions Type conversions
@ -126,11 +126,11 @@ The syntax for type conversions is ``destination_type(expression_to_convert)``
(like an ordinary call): (like an ordinary call):
.. code-block:: nim .. code-block:: nim
proc getID(x: TPerson): int = proc getID(x: Person): int =
TStudent(x).id Student(x).id
The ``InvalidObjectConversionError`` exception is raised if ``x`` is not a The ``InvalidObjectConversionError`` exception is raised if ``x`` is not a
``TStudent``. ``Student``.
Object variants Object variants
@ -144,16 +144,16 @@ An example:
# This is an example how an abstract syntax tree could be modeled in Nim # This is an example how an abstract syntax tree could be modeled in Nim
type type
TNodeKind = enum # the different node types NodeKind = enum # the different node types
nkInt, # a leaf with an integer value nkInt, # a leaf with an integer value
nkFloat, # a leaf with a float value nkFloat, # a leaf with a float value
nkString, # a leaf with a string value nkString, # a leaf with a string value
nkAdd, # an addition nkAdd, # an addition
nkSub, # a subtraction nkSub, # a subtraction
nkIf # an if statement nkIf # an if statement
PNode = ref TNode Node = ref NodeObj
TNode = object NodeObj = object
case kind: TNodeKind # the ``kind`` field is the discriminator case kind: NodeKind # the ``kind`` field is the discriminator
of nkInt: intVal: int of nkInt: intVal: int
of nkFloat: floatVal: float of nkFloat: floatVal: float
of nkString: strVal: string of nkString: strVal: string
@ -228,21 +228,21 @@ is needed:
.. code-block:: nim .. code-block:: nim
type type
TSocket* = object of RootObj Socket* = object of RootObj
FHost: int # cannot be accessed from the outside of the module FHost: int # cannot be accessed from the outside of the module
# the `F` prefix is a convention to avoid clashes since # the `F` prefix is a convention to avoid clashes since
# the accessors are named `host` # the accessors are named `host`
proc `host=`*(s: var TSocket, value: int) {.inline.} = proc `host=`*(s: var Socket, value: int) {.inline.} =
## setter of hostAddr ## setter of hostAddr
s.FHost = value s.FHost = value
proc host*(s: TSocket): int {.inline.} = proc host*(s: Socket): int {.inline.} =
## getter of hostAddr ## getter of hostAddr
s.FHost s.FHost
var var
s: TSocket s: Socket
s.host = 34 # same as `host=`(s, 34) s.host = 34 # same as `host=`(s, 34)
(The example also shows ``inline`` procedures.) (The example also shows ``inline`` procedures.)
@ -253,10 +253,10 @@ The ``[]`` array access operator can be overloaded to provide
.. code-block:: nim .. code-block:: nim
type type
TVector* = object Vector* = object
x, y, z: float x, y, z: float
proc `[]=`* (v: var TVector, i: int, value: float) = proc `[]=`* (v: var Vector, i: int, value: float) =
# setter # setter
case i case i
of 0: v.x = value of 0: v.x = value
@ -264,7 +264,7 @@ The ``[]`` array access operator can be overloaded to provide
of 2: v.z = value of 2: v.z = value
else: assert(false) else: assert(false)
proc `[]`* (v: TVector, i: int): float = proc `[]`* (v: Vector, i: int): float =
# getter # getter
case i case i
of 0: result = v.x of 0: result = v.x
@ -313,27 +313,27 @@ dispatching:
.. code-block:: nim .. code-block:: nim
type type
TThing = object of RootObj Thing = object of RootObj
TUnit = object of TThing Unit = object of Thing
x: int x: int
method collide(a, b: TThing) {.inline.} = method collide(a, b: Thing) {.inline.} =
quit "to override!" quit "to override!"
method collide(a: TThing, b: TUnit) {.inline.} = method collide(a: Thing, b: Unit) {.inline.} =
echo "1" echo "1"
method collide(a: TUnit, b: TThing) {.inline.} = method collide(a: Unit, b: Thing) {.inline.} =
echo "2" echo "2"
var var
a, b: TUnit a, b: Unit
collide(a, b) # output: 2 collide(a, b) # output: 2
As the example demonstrates, invocation of a multi-method cannot be ambiguous: As the example demonstrates, invocation of a multi-method cannot be ambiguous:
Collide 2 is preferred over collide 1 because the resolution works from left to Collide 2 is preferred over collide 1 because the resolution works from left to
right. Thus ``TUnit, TThing`` is preferred over ``TThing, TUnit``. right. Thus ``Unit, Thing`` is preferred over ``Thing, Unit``.
**Perfomance note**: Nim does not produce a virtual method table, but **Perfomance note**: Nim does not produce a virtual method table, but
generates dispatch trees. This avoids the expensive indirect branch for method generates dispatch trees. This avoids the expensive indirect branch for method
@ -479,18 +479,18 @@ containers:
.. code-block:: nim .. code-block:: nim
type type
TBinaryTree[T] = object # TBinaryTree is a generic type with BinaryTreeObj[T] = object # BinaryTree is a generic type with
# with generic param ``T`` # with generic param ``T``
le, ri: ref TBinaryTree[T] # left and right subtrees; may be nil le, ri: BinaryTree[T] # left and right subtrees; may be nil
data: T # the data stored in a node data: T # the data stored in a node
PBinaryTree*[T] = ref TBinaryTree[T] # type that is exported BinaryTree*[T] = ref BinaryTreeObj[T] # type that is exported
proc newNode*[T](data: T): PBinaryTree[T] = proc newNode*[T](data: T): BinaryTree[T] =
# constructor for a node # constructor for a node
new(result) new(result)
result.data = data result.data = data
proc add*[T](root: var PBinaryTree[T], n: PBinaryTree[T]) = proc add*[T](root: var BinaryTree[T], n: BinaryTree[T]) =
# insert a node into the tree # insert a node into the tree
if root == nil: if root == nil:
root = n root = n
@ -511,15 +511,15 @@ containers:
return return
it = it.ri it = it.ri
proc add*[T](root: var PBinaryTree[T], data: T) = proc add*[T](root: var BinaryTree[T], data: T) =
# convenience proc: # convenience proc:
add(root, newNode(data)) add(root, newNode(data))
iterator preorder*[T](root: PBinaryTree[T]): T = iterator preorder*[T](root: BinaryTree[T]): T =
# Preorder traversal of a binary tree. # Preorder traversal of a binary tree.
# Since recursive iterators are not yet implemented, # Since recursive iterators are not yet implemented,
# this uses an explicit stack (which is more efficient anyway): # this uses an explicit stack (which is more efficient anyway):
var stack: seq[PBinaryTree[T]] = @[root] var stack: seq[BinaryTree[T]] = @[root]
while stack.len > 0: while stack.len > 0:
var n = stack.pop() var n = stack.pop()
while n != nil: while n != nil:
@ -528,7 +528,7 @@ containers:
n = n.le # and follow the left pointer n = n.le # and follow the left pointer
var var
root: PBinaryTree[string] # instantiate a PBinaryTree with ``string`` root: BinaryTree[string] # instantiate a BinaryTree with ``string``
add(root, newNode("hello")) # instantiates ``newNode`` and ``add`` add(root, newNode("hello")) # instantiates ``newNode`` and ``add``
add(root, "world") # instantiates the second ``add`` proc add(root, "world") # instantiates the second ``add`` proc
for str in preorder(root): for str in preorder(root):
@ -863,7 +863,7 @@ precisely made for compilation time (just like `gorge <system.html#gorge>`_
which executes an external program and captures its output). which executes an external program and captures its output).
The interesting thing is that our macro does not return a runtime `Table The interesting thing is that our macro does not return a runtime `Table
<tables.html#TTable>`_ object. Instead, it builds up Nim source code into <tables.html#Table>`_ object. Instead, it builds up Nim source code into
the ``source`` variable. For each line of the configuration file a ``const`` the ``source`` variable. For each line of the configuration file a ``const``
variable will be generated (line 15). To avoid conflicts we prefix these variable will be generated (line 15). To avoid conflicts we prefix these
variables with ``cfg``. In essence, what the compiler is doing is replacing variables with ``cfg``. In essence, what the compiler is doing is replacing