aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-05-24 22:32:01 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-05-26 02:42:07 -0400
commit33808b0e6ae8dbf6a511522f1159d9abc3af5dcb (patch)
tree120cf633999c312eb797163474936d850aed3c10
parentb8c885ec190b739d49e007dbf5d909fb45ab6430 (diff)
downloadlibrambutan-33808b0e6ae8dbf6a511522f1159d9abc3af5dcb.tar.gz
librambutan-33808b0e6ae8dbf6a511522f1159d9abc3af5dcb.zip
Docs: lang/api/constants.rst touchups
Mostly, make it less pedantic. Also some stylistic and content fixes.
-rw-r--r--docs/source/lang/api/constants.rst94
1 files changed, 44 insertions, 50 deletions
diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst
index 3ba99f0..6f69dfe 100644
--- a/docs/source/lang/api/constants.rst
+++ b/docs/source/lang/api/constants.rst
@@ -62,7 +62,7 @@ pin is configured as an ``INPUT`` (using :ref:`pinMode()
<lang-digitalread>`, the microcontroller will report ``HIGH`` if a
voltage of 3 volts or more is present at the pin.
-When a pin is configured to ``OUTPUT`` with pinMode, and set to
+When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to
``HIGH`` with :ref:`digitalWrite() <lang-digitalwrite>`, the pin is at
3.3 volts. In this state it can *source* current, e.g. light an LED
that is connected through a series resistor to ground, or to another
@@ -82,9 +82,9 @@ pin.
When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to
``LOW`` with :ref:`digitalWrite() <lang-digitalwrite>`, the
-microcontroller will attempt to keep that pin's voltage at 0V. In this
+microcontroller will attempt to keep that pin's voltage at 0 V. In this
state it can *sink* current, e.g. light an LED that is connected
-through a series resistor to +3.3V, or to another pin configured as an
+through a series resistor to +3.3 V, or to another pin configured as an
output, and set to ``HIGH``.
Pin Modes
@@ -104,11 +104,11 @@ modes, see the :ref:`pinMode() <lang-pinmode>` reference page.
INPUT
^^^^^
-Maple (STM32) pins configured as ``INPUT`` are said to be in a
-high-impedance state. One way of explaining this is that pins
-configured as ``INPUT`` make extremely small demands on the circuit
-that they are sampling. This makes them useful for reading a sensor,
-but not powering an LED.
+Pins configured as ``INPUT`` are said to be in a *high-impedance
+state*. One way of explaining this is that pins configured as
+``INPUT`` make very few demans on circuit that they are connected
+to. This makes them useful for reading a sensor, but not powering an
+LED.
.. _lang-constants-output:
@@ -117,31 +117,31 @@ OUTPUT
Pins configured as ``OUTPUT`` with :ref:`pinMode() <lang-pinmode>` are
said to be in a low-impedance state. This means that they can provide
-a substantial amount of current to other circuits. STM32 pins can
-source (provide positive current) or sink (provide negative current)
-up to 50 mA (milliamps) of current to other devices/circuits. This
-makes them useful for powering LEDs, but useless for reading sensors.
+a substantial amount of current to other circuits. Pins can source
+(provide positive current) or sink (provide negative current) up to 50
+mA (milliamps) of current to other devices/circuits. This makes them
+useful for powering LEDs, but useless for reading sensors.
Pins configured as outputs can also be damaged or destroyed if short
-circuited to either ground or 3.3V power rails. The amount of current
-provided by an STM32 pin is also not enough to power most relays or
-motors, and some interface circuitry will be required.
+circuited to either ground or power supplies. The amount of current
+provided by a pin is also not enough to power most relays or motors,
+and some interface circuitry will be required.
.. _lang-constants-integers:
Integer Constants
-----------------
-Integer constants (or more properly speaking, integer *literals*) are
-numbers used directly in a sketch, like ``123``. By default, an
-integer literal is treated as a (signed) :ref:`int <lang-int>`, but
-you can change this with the U and L modifiers (see :ref:`below
-<lang-constants-integers-u-l>`). You can specify negative numbers by
-putting a minus sign in front, like ``-123``.
+Integer constants are numbers used directly in a sketch, like
+``123``. By default, an integer constant is treated as a (signed)
+:ref:`int <lang-int>`, but you can change this with the U and L
+modifiers (see :ref:`below <lang-constants-integers-u-l>`). You can
+specify negative numbers by putting a minus sign in front, like
+``-123``.
-Normally, integer literals are treated as base 10 (decimal) integers,
+Normally, integer constants are treated as base 10 (decimal) integers,
but special notation (formatters) may be used to enter numbers in
-other bases. These are summarized in the following table:
+other bases. These are explained in the following table:
.. list-table::
:header-rows: 1
@@ -172,8 +172,8 @@ other bases. These are summarized in the following table:
- Characters 0-9, A-F (or a-f) valid
Binary constants (like ``B1111011``) for values between 0 and 255 are
-supported for compatibility with Arduino only. Their use in new
-programs is discouraged.
+supported for compatibility with Arduino only. You shouldn't use them
+in new programs.
.. _lang-constants-integers-dec:
@@ -187,8 +187,7 @@ For example, the decimal literal ``101`` is one hundred and one: 1×10\
.. _lang-constants-integers-bin:
**Binary** is base two. Only characters 0 and 1 are valid. Binary
-literals are indicated by the prefix ``0b`` (this is a :ref:`GCC
-<arm-gcc>` extension; it's not standard C++).
+literals are indicated by the prefix ``0b``.
For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` +
0×2\ :sup:`1` + 1×2\ :sup:`0` = 5.
@@ -203,19 +202,19 @@ For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` +
.. warning:: Bugs sometimes result by (unintentionally) including a
leading "0" before an integer literal, which makes the compiler
- interpret it in octal.
+ treat it as an octal number.
.. _lang-constants-integers-hex:
**Hexadecimal** (or "hex") is base sixteen. Valid characters are 0
through 9 and letters A through F; A has the value 10, B is 11, up to
-F, which is 15. Hex values are indicated by the prefix ``0x``. A-F
-may be typed in upper or lower case (a-f).
+F, which is 15. Hex values are indicated by the prefix ``0x``. A-F
+can be typed in upper or lower case (a-f).
-For example, the hexadecimal literal ``0x101`` is two hundred fifty
+For example, the hexadecimal constant ``0x101`` is two hundred fifty
seven: 1×16\ :sup:`2` + 0×16\ :sup:`1` + 1×16\ :sup:`0` = 257.
-The hexadecimal literal ``0xCF2`` is three thousand, three hundred
+The hexadecimal constant ``0xCF2`` is three thousand, three hundred
fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314.
(Remember that in hex, ``A`` means 10, and counting up, ``B``\ =11, so
@@ -226,10 +225,10 @@ fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314.
U and L Suffixes
^^^^^^^^^^^^^^^^
-By default, an integer constant is treated as an :ref:`int
-<lang-int>`, with the attendant :ref:`limitations in values
-<lang-int-overflow>`. To specify an integer constant with another data
-type, follow it with:
+By default, an integer constant is treated as an :ref:`int <lang-int>`
+(and must be in the int type's :ref:`range limits
+<lang-int-overflow>`). To specify an integer constant with another
+data type, follow it with:
- a ``u`` or ``U`` to interpret the constant as an unsigned value.
For example, ``33U`` is an :ref:`unsigned int <lang-unsignedint>`.
@@ -253,17 +252,12 @@ type, follow it with:
Floating-Point Constants
------------------------
-Similar to integer literals, floating point constants (properly:
-floating-point *literals*) are used to make code more readable.
-Floating point literals are swapped at compile time for the value to
-which the expression evaluates.
-
-A floating point literal is any number which includes a decimal point.
-For instance, ``3.0`` is a floating-point literal for the number 3.
-By default, a floating-point literal is a :ref:`double <lang-double>`.
-In order for the literal to be interpreted as a :ref:`float
-<lang-float>`, you can write ``f`` directly after it. For example,
-``3.0f`` is a floating-point literal with type ``float``.
+A floating point constant is any number which includes a decimal
+point. For instance, ``3.0`` is a floating-point constant for the
+number 3. By default, a floating-point constant is a :ref:`double
+<lang-double>`. In order for the constant to be interpreted as a
+:ref:`float <lang-float>`, you can write ``f`` directly after it. For
+example, ``3.0f`` is a floating-point constant with type ``float``.
Floating point constants can also be expressed in a variety of
scientific notation. ``E`` and ``e`` are both accepted as valid
@@ -273,7 +267,7 @@ exponent indicators. Some examples are given in the following table:
.. list-table::
:header-rows: 1
- * - Floating-point literal
+ * - Floating-point constant
- Evaluates to
- Alternate expression
@@ -297,8 +291,8 @@ Board-Specific Constants
There are several :ref:`board-specific constants <lang-board-values>`
whose value depends on which LeafLabs board you have. If you use
them, it will help make sure that your code will work well on all
-LeafLabs boards, not just the one you have. This will make it much
-easier to share your code with others.
+LeafLabs boards, not just the one you have. This will make it easier
+to share your code with others.
For example, the pin number connected to the board's built-in LED is
different on the different boards, but the board-specific constant