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

easier comment handling; breaks code

Browse source
This commit is contained in:
Araq 2014-04-25 21:41:56 +02:00
commit e6cad814a3
8 changed files with 32 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

35
doc/manual.txt
View file

@ -154,35 +154,22 @@ Comments
`Comments`:idx: start anywhere outside a string or character literal with the
hash character ``#``.
Comments consist of a concatenation of `comment pieces`:idx:. A comment piece
starts with ``#`` and runs until the end of the line. The end of line characters
belong to the piece. If the next line only consists of a comment piece which is
aligned to the preceding one, it does not start a new comment:
belong to the piece. If the next line only consists of a comment piece with
no other tokens between it and the preceding one, it does not start a new
comment:
.. code-block:: nimrod
i = 0 # This is a single comment over multiple lines belonging to the
# assignment statement. The scanner merges these two pieces.
# This is a new comment belonging to the current block, but to no particular
# statement.
i = i + 1 # This a new comment that is NOT
echo(i) # continued here, because this comment refers to the echo statement
i = 0 # This is a single comment over multiple lines.
# The scanner merges these two pieces.
# The comment continues here.
The alignment requirement does not hold if the preceding comment piece ends in
a backslash (followed by optional whitespace):
.. code-block:: nimrod
type
TMyObject {.final, pure, acyclic.} = object # comment continues: \
# we have lots of space here to comment 'TMyObject'.
# This line belongs to the comment as it's properly aligned.
Comments are tokens; they are only allowed at certain places in the input file
as they belong to the syntax tree! This feature enables perfect source-to-source
transformations (such as pretty-printing) and superior documentation generators.
A nice side-effect is that the human reader of the code always knows exactly
which code snippet the comment refers to.
`Documentation comments`:idx: are comments that start with two ``##``.
Documentation comments are tokens; they are only allowed at certain places in
the input file as they belong to the syntax tree!
Identifiers & Keywords
@ -5688,7 +5675,7 @@ Spawn
Nimrod has a builtin thread pool that can be used for CPU intensive tasks. For
IO intensive tasks the upcoming ``async`` and ``await`` features should be
used instead. `spawn`:idx: is used to pass a task to the thread pool:
used. `spawn`:idx: is used to pass a task to the thread pool:
.. code-block:: nimrod
proc processLine(line: string) =

37
doc/tut1.txt
View file

@ -111,41 +111,16 @@ Comments
--------
`Comments`:idx: start anywhere outside a string or character literal with the
hash character ``#``. Documentation comments start with ``##``. Multiline
comments need to be aligned at the same column:
hash character ``#``. Documentation comments start with ``##``:
.. code-block:: nimrod
# A comment.
i = 0 # This is a single comment over multiple lines belonging to the
# assignment statement.
# This is a new comment belonging to the current block, but to no particular
# statement.
i = i + 1 # This a new comment that is NOT
echo(i) # continued here, because this comment refers to the echo statement
var myVariable: int ## a documentation comment
The alignment requirement does not hold if the preceding comment piece ends in
a backslash:
.. code-block:: nimrod
type
TMyObject {.final, pure, acyclic.} = object # comment continues: \
# we have lots of space here to comment 'TMyObject'.
# This line belongs to the comment as it's properly aligned.
Comments are tokens; they are only allowed at certain places in the input file
as they belong to the syntax tree! This feature enables perfect source-to-source
transformations (such as pretty-printing) and simpler documentation generators.
A nice side-effect is that the human reader of the code always knows exactly
which code snippet the comment refers to. Since comments are a proper part of
the syntax, watch their indentation:
.. code-block::
echo("Hello!")
# comment has the same indentation as above statement -> fine
echo("Hi!")
# comment has not the correct indentation level -> syntax error!
Documentation comments are tokens; they are only allowed at certain places in
the input file as they belong to the syntax tree! This feature enables simpler
documentation generators.
**Note**: To comment out a large piece of code, it is often better to use a
``when false:`` statement.