From 90cd4bc2382554bfa808baca120ad6dc108b9e06 Mon Sep 17 00:00:00 2001 From: Allen Luce Date: Thu, 23 Jun 2016 14:48:20 -0700 Subject: [PATCH] Documentation cleanup, part one. --- doc/source/reference/introduction.rst | 10 +-- doc/source/reference/language/datatypes.rst | 79 ++++++++++--------- .../reference/language/lexical_structure.rst | 26 +++--- 3 files changed, 59 insertions(+), 56 deletions(-) diff --git a/doc/source/reference/introduction.rst b/doc/source/reference/introduction.rst index 348fcb6..bc83447 100644 --- a/doc/source/reference/introduction.rst +++ b/doc/source/reference/introduction.rst @@ -7,10 +7,10 @@ Introduction .. index:: single: introduction -Squirrel is a high level imperative-OO programming language, designed to be a powerful -scripting tool that fits in the size, memory bandwidth, and real-time requirements of +Squirrel is a high-level, imperative-OO programming language, designed to be a powerful +scripting tool that fits within the size, memory bandwidth, and real-time requirements of applications like games. -Although Squirrel offers a wide range of features like dynamic typing, delegation, higher +Squirrel offers a wide range of features like dynamic typing, delegation, higher order functions, generators, tail recursion, exception handling, automatic memory -management, both compiler and virtual machine fit together in about 6k lines of C++ -code. \ No newline at end of file +management while fitting both compiler and virtual machine into about 6k lines of C++ +code. diff --git a/doc/source/reference/language/datatypes.rst b/doc/source/reference/language/datatypes.rst index 4ffc34f..843ed8b 100644 --- a/doc/source/reference/language/datatypes.rst +++ b/doc/source/reference/language/datatypes.rst @@ -4,10 +4,11 @@ Values and Data types ===================== -Squirrel is a dynamically typed language so variables do not have a type, although they -refer to a value that does have a type. -Squirrel basic types are integer, float, string, null, table, array, function, generator, -class, instance, bool, thread and userdata. +While Squirrel is a dynamically typed language and variables do not +have a type, different operations may interpret the variable as +containing a type. Squirrel's basic types are integer, float, string, +null, table, array, function, generator, class, instance, bool, thread +and userdata. .. _userdata-index: @@ -15,7 +16,7 @@ class, instance, bool, thread and userdata. Integer -------- -An Integer represents a 32 bits (or better) signed number.:: +An Integer represents a 32 bit (or better) signed number.:: local a = 123 //decimal local b = 0x0012 //hexadecimal @@ -26,7 +27,7 @@ An Integer represents a 32 bits (or better) signed number.:: Float -------- -A float represents a 32 bits (or better) floating point number.:: +A float represents a 32 bit (or better) floating point number.:: local a=1.0 local b=0.234 @@ -35,24 +36,27 @@ A float represents a 32 bits (or better) floating point number.:: String -------- -Strings are an immutable sequence of characters to modify a string is necessary create a new one. +Strings are an immutable sequence of characters. In order to modify a +string is it necessary create a new one. -Squirrel's strings, behave like C or C++, are delimited by quotation marks(``"``) and can contain -escape sequences(``\t``, ``\a``, ``\b``, ``\n``, ``\r``, ``\v``, ``\f``, ``\\``, ``\"``, ``\'``, ``\0``, -``\x``, ``\u`` and ``\U``). +Squirrel's strings are similar to strings in C or C++. They are +delimited by quotation marks(``"``) and can contain escape +sequences (``\t``, ``\a``, ``\b``, ``\n``, ``\r``, ``\v``, ``\f``, +``\\``, ``\"``, ``\'``, ``\0``, ``\x``, ``\u`` and +``\U``). -Verbatim string literals begin with ``@"`` and end with the matching quote. -Verbatim string literals also can extend over a line break. If they do, they -include any white space characters between the quotes: :: +Verbatim string literals do not interpret escape sequences. They begin +with ``@"`` and end with the matching quote. Verbatim string literals +also can extend over a line break. If they do, they include any white +space characters between the quotes: :: local a = "I'm a wonderful string\n" // has a newline at the end of the string local x = @"I'm a verbatim string\n" - // the \n is copied in the string same as \\n in a regular string "I'm a verbatim string\n" + // the \n is literal, similar to "\\n" in a regular string. -The only exception to the "no escape sequence" rule for verbatim -string literals is that you can put a double quotation mark inside a -verbatim string by doubling it: :: +However, a doubled quotation mark within a verbatim string is replaced +by a single quotation mark: :: local multiline = @" this is a multiline string @@ -73,7 +77,7 @@ reference. The type Null has exactly one value, called null.:: Bool -------- -the bool data type can have only two. They are the literals ``true`` +Bool is a double-valued (Boolean) data type. Its literals are ``true`` and ``false``. A bool value expresses the validity of a condition (tells whether the condition is true or false).:: @@ -83,7 +87,8 @@ and ``false``. A bool value expresses the validity of a condition Table -------- -Tables are associative containers implemented as pairs of key/value (called a slot).:: +Tables are associative containers implemented as a set of key/value pairs +called slots.:: local t={} local test= @@ -96,7 +101,7 @@ Tables are associative containers implemented as pairs of key/value (called a sl Array -------- -Arrays are simple sequence of objects, their size is dynamic and their index starts always from 0.:: +Arrays are simple sequence of objects. Their size is dynamic and their index always starts from 0.:: local a = ["I'm","an","array"] local b = [null] @@ -106,46 +111,48 @@ Arrays are simple sequence of objects, their size is dynamic and their index sta Function -------- -Functions are similar to those in other C-like languages and to most programming -languages in general, however there are a few key differences (see below). +Functions are similar to those in other C-like languages with a few key differences (see below). -------- Class -------- -Classes are associative containers implemented as pairs of key/value. Classes are created through -a 'class expression' or a 'class statement'. class members can be inherited from another class object -at creation time. After creation members can be added until a instance of the class is created. +Classes are associative containers implemented as sets of key/value +pairs. Classes are created through a 'class expression' or a 'class +statement'. class members can be inherited from another class object +at creation time. After creation, members can be added until an +instance of the class is created. -------------- Class Instance -------------- -Class instances are created by calling a *class object*. Instances, as tables, are -implemented as pair of key/value. Instances members cannot be dynamically added or removed; however the value of the members can be changed. - - +Class instances are created by calling a *class object*. Instances, as +tables, are implemented as sets of key/value pairs. Instance members +cannot be dynamically added or removed; however the value of the +members can be changed. --------- Generator --------- -Generators are functions that can be suspended with the statement 'yield' and resumed -later (see :ref:`Generators `). +Generators are functions that can be suspended with the statement +'yield' and resumed later (see :ref:`Generators `). --------- Userdata --------- -Userdata objects are blobs of memory(or pointers) defined by the host application but -stored into Squirrel variables (See :ref:`Userdata and UserPointers `). - +Userdata objects are blobs of memory or pointers defined by the host +application but stored within Squirrel variables (See :ref:`Userdata +and UserPointers `). --------- Thread --------- -Threads are objects that represents a cooperative thread of execution, also known as coroutines. +Threads are objects representing a cooperative thread of execution, +also known as coroutines. -------------- Weak Reference @@ -153,5 +160,3 @@ Weak Reference Weak References are objects that point to another (non-scalar) object but do not own a strong reference to it. (See :ref:`Weak References `). - - diff --git a/doc/source/reference/language/lexical_structure.rst b/doc/source/reference/language/lexical_structure.rst index 05cba40..72e23f5 100644 --- a/doc/source/reference/language/lexical_structure.rst +++ b/doc/source/reference/language/lexical_structure.rst @@ -13,11 +13,11 @@ Identifiers .. index:: single: identifiers -Identifiers start with a alphabetic character or '_' followed by any number of alphabetic -characters, '_' or digits ([0-9]). Squirrel is a case sensitive language, this means that the -lowercase and uppercase representation of the same alphabetic character are considered -different characters. For instance "foo", "Foo" and "fOo" will be treated as 3 distinct -identifiers. +Identifiers start with an alphabetic character or the symbol '_' followed by any number +of alphabetic characters, '_' or digits ([0-9]). Squirrel is a case sensitive language +meaning that the lowercase and uppercase representation of the same alphabetic +character are considered different characters. For instance, "foo", "Foo" and "fOo" are +treated as 3 distinct identifiers. ----------- Keywords @@ -25,7 +25,7 @@ Keywords .. index:: single: keywords -The following words are reserved words by the language and cannot be used as identifiers: +The following words are reserved and cannot be used as identifiers: +------------+------------+-----------+------------+------------+-------------+ | base | break | case | catch | class | clone | @@ -69,7 +69,7 @@ Other tokens single: delimiters single: other tokens -Other used tokens are: +Other significant tokens are: +----------+----------+----------+----------+----------+----------+ | ``{`` | ``}`` | ``[`` | ``]`` | ``.`` | ``:`` | @@ -86,7 +86,7 @@ Literals single: string literals single: numeric literals -Squirrel accepts integer numbers, floating point numbers and strings literals. +Squirrel accepts integer numbers, floating point numbers and string literals. +-------------------------------+------------------------------------------+ | ``34`` | Integer number(base 10) | @@ -131,7 +131,7 @@ A comment is text that the compiler ignores but that is useful for programmers. Comments are normally used to embed annotations in the code. The compiler treats them as white space. -The ``/*`` (slash, asterisk) characters, followed by any +A comment can be ``/*`` (slash, asterisk) characters, followed by any sequence of characters (including new lines), followed by the ``*/`` characters. This syntax is the same as ANSI C.:: @@ -141,9 +141,9 @@ followed by the ``*/`` characters. This syntax is the same as ANSI C.:: this lines will be ignored by the compiler */ -The ``//`` (two slashes) characters, followed by any sequence of characters. -A new line not immediately preceded by a backslash terminates this form of comment. -It is commonly called a *"single-line comment."*:: +A comment can also be ``//`` (two slashes) characters, followed by any sequence of +characters. A new line not immediately preceded by a backslash terminates this form of +comment. It is commonly called a *"single-line comment."*:: //this is a single line comment. this line will be ignored by the compiler @@ -152,5 +152,3 @@ The character ``#`` is an alternative syntax for single line comment.:: # this is also a single line comment. This to facilitate the use of squirrel in UNIX-style shell scripts. - -