aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-06-10 10:25:17 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-06-10 10:43:01 -0400
commitc765320c83dd25f026eb86785e55773b72a6bcd2 (patch)
treeae62b828ff6a9e46bc903621fbde190a76e4c032
parent6cc1ea450b288d76d2b2d66176abba78dea6e467 (diff)
downloadlibrambutan-c765320c83dd25f026eb86785e55773b72a6bcd2.tar.gz
librambutan-c765320c83dd25f026eb86785e55773b72a6bcd2.zip
Docs: move ASSERT() to its own page.
ASSERT() was previously documented in language.rst. Move it to a new lang/api/assert.rst.
-rw-r--r--docs/source/jtag.rst12
-rw-r--r--docs/source/lang/api/assert.rst30
-rw-r--r--docs/source/language.rst53
-rw-r--r--docs/source/timers.rst9
-rw-r--r--docs/source/troubleshooting.rst2
5 files changed, 51 insertions, 55 deletions
diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst
index 4151a53..0558a29 100644
--- a/docs/source/jtag.rst
+++ b/docs/source/jtag.rst
@@ -2,9 +2,8 @@
.. _jtag:
-======
- JTAG
-======
+JTAG
+====
.. FIXME [0.1.0] Updated adapter schematic, better information
@@ -17,10 +16,9 @@ and hardware peripherals (we use it when working on :ref:`libmaple
<libmaple>`) or to flash a new bootloader.
Note that the STM32 on the Maple has a built-in low level serial
-debugger which could also be used to flash bootloaders, and that the
-:ref:`ASSERT <language-assert>` framework allows basic debugging over
-a USART serial channel. We expect only fairly advanced users to use
-this feature.
+debugger which could also be used to flash bootloaders, and
+:ref:`lang-assert` allows basic debugging over a USART serial channel.
+We expect only fairly advanced users to use this feature.
.. contents:: Contents
:local:
diff --git a/docs/source/lang/api/assert.rst b/docs/source/lang/api/assert.rst
new file mode 100644
index 0000000..76330b6
--- /dev/null
+++ b/docs/source/lang/api/assert.rst
@@ -0,0 +1,30 @@
+.. highlight:: cpp
+
+.. _lang-assert:
+
+``ASSERT(...)``
+===============
+
+ASSERT() can be very useful for basic program debugging. It accepts a
+boolean; for example::
+
+ ASSERT(state == WAIT);
+
+Zero is false and any other number is true. If the boolean is true,
+the assertion passes and the program continues as usual. If it is
+false, the assertion fails: the program is halted, debug information
+is printed to USART2, and the status LED begins to throb (it's
+noticeably different from blinking). The debug information is printed
+at 9600 baud and consists of the filename and line number where the
+ASSERT() failed.
+
+Including assertions in a program increases the program size. When
+using libmaple **from the command line only**, they can be disabled by
+making the definition ::
+
+ #define DEBUG_LEVEL DEBUG_NONE
+
+before including either wirish.h or libmaple.h. In this case, all
+assertions will pass without any lost clock cycles. Note that this
+will **not work in the IDE**; even with this definition, assertions
+will still be enabled.
diff --git a/docs/source/language.rst b/docs/source/language.rst
index 3ecbe43..be085f2 100644
--- a/docs/source/language.rst
+++ b/docs/source/language.rst
@@ -12,8 +12,7 @@ language used to program the `Arduino <http://arduino.cc/>`_ boards.
.. TODO [0.2.0?] Wiring tutorial
-C or C++ programmers curious about the differences between the Wiring
-language and C++ may wish to skip to the
+C or C++ programmers may wish to skip to the
:ref:`arduino_c_for_c_hackers`.
.. contents:: Contents
@@ -21,8 +20,7 @@ language and C++ may wish to skip to the
.. admonition:: **Looking for Something Else?**
- - See the :ref:`libraries` for extra built-in libraries for dealing
- with different kinds of hardware.
+ - See the :ref:`libraries` for extra built-in libraries.
- If you're looking for something from the C standard library (like
``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler
@@ -31,17 +29,17 @@ language and C++ may wish to skip to the
use of any of its header files. However, dynamic memory allocation
(``malloc()``, etc.) is not available.
- - If you're looking for pointers to low-level details, see this page's
- :ref:`Recommended Reading <language-recommended-reading>`.
+ - If you're looking for pointers to low-level details, see
+ :ref:`libmaple` and this page's :ref:`Recommended Reading
+ <language-recommended-reading>`.
.. _language-lang-docs:
Maple Language Reference
------------------------
-The following table summarizes the most important core language
-features. An exhaustive index is available at the
-:ref:`language-index`.
+This table is a summary of the most important language features. See
+the :ref:`language-index` for a complete listing.
+--------------------------------------------+----------------------------------------------+---------------------------------------------------+
| Structure | Variables | Functions |
@@ -68,7 +66,7 @@ features. An exhaustive index is available at the
| | | |
|* :ref:`continue <lang-continue>` |**Data Types** |* :ref:`analogRead() <lang-analogread>` |
| | | |
-|* :ref:`return <lang-return>` | The size of each datatype, in bytes, is |* :ref:`pwmWrite() <lang-pwmwrite>` |
+|* :ref:`return <lang-return>` | The size of each data type, in bytes, is |* :ref:`pwmWrite() <lang-pwmwrite>` |
| | given in parentheses where appropriate. | (:ref:`analogWrite() <lang-analogwrite>` is |
|* :ref:`goto <lang-goto>` | | also available, though its use is discouraged) |
| | *Note*: The ``word`` type is (deliberately) | |
@@ -144,7 +142,7 @@ features. An exhaustive index is available at the
| | | |
|* :ref:`& reference operator |* :ref:`sizeof() <lang-sizeof>` |* :ref:`bitClear() <lang-bitclear>` |
| <lang-pointer>` | | |
-| | |* :ref:`bit() <lang-bit>` |
+| |* :ref:`ASSERT() <lang-assert>` |* :ref:`bit() <lang-bit>` |
| | | |
|**Bitwise Operators** | | |
| | |**External Interrupts** |
@@ -205,35 +203,6 @@ features. An exhaustive index is available at the
| | | |
+--------------------------------------------+----------------------------------------------+---------------------------------------------------+
-.. _language-assert:
-
-``ASSERT(...)``
----------------
-
-The ``ASSERT()`` function can be very useful for basic program
-debugging. It accepts a boolean; for example::
-
- ASSERT(state == WAIT);
-
-Zero is false and any other number is true. If the boolean is true, the
-assertion passes and the program continues as usual. If it is false,
-the assertion fails: the program is halted, debug information is
-printed to USART2, and the status LED begins to throb in intensity
-(it's noticeably different from blinking). The debug information is
-printed at 9600 baud and consists of the filename and line number
-where the particular assertion failed.
-
-Including assertions in a program increases the program size. When
-using libmaple **from the command line only**, they can be disabled by
-making the definition ::
-
- #define DEBUG_LEVEL DEBUG_NONE
-
-before including either wirish.h or libmaple.h. In this case, all
-assertions will pass without any lost clock cycles. Note that this
-will **not work in the IDE**; even with this definition, assertions
-will still be enabled.
-
.. _language-missing-features:
Missing Arduino Features
@@ -301,7 +270,7 @@ Note for C/C++ Hackers
This is a note for programmers comfortable with C or C++ who want a
better understanding of the differences between C++ and the Wiring
-language.
+language.
The good news is that the differences are relatively few; Wiring is
just a thin wrapper around C++. Some potentially better news is that
@@ -378,7 +347,7 @@ behaves roughly like::
// Call user loop() forever.
while (true) {
- loop();
+ loop();
}
}
diff --git a/docs/source/timers.rst b/docs/source/timers.rst
index e23579d..b6c0886 100644
--- a/docs/source/timers.rst
+++ b/docs/source/timers.rst
@@ -66,11 +66,10 @@ Working with timers and interrupts can be tricky; they are a somewhat
"advanced" topic. The following subsections explain some common
problems associated with using timers and timer interrupts.
-In general: start simple, test with :ref:`ASSERT() <language-assert>`,
-and don't try to do too much in your interrupt handlers! Make sure
-that what you're trying to do in a handler isn't going to block other
-interrupts from firing, if those other interrupts are important for
-your program.
+In general: start simple, test with :ref:`lang-assert`, and don't try
+to do too much in your interrupt handlers! Make sure that what you're
+trying to do in a handler isn't going to block other interrupts from
+firing, if those other interrupts are important for your program.
.. _timers-pwm-conflicts:
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
index 3174f14..b679b9c 100644
--- a/docs/source/troubleshooting.rst
+++ b/docs/source/troubleshooting.rst
@@ -18,7 +18,7 @@ The LED is throbbing and my program is stopped!
-----------------------------------------------
The LED throbs when there has been a failed software :ref:`assertion
-<language-assert>` or some other error.
+<lang-assert>` or some other error.
There are a few issues with the bootloader which mean you might not be
able to upload your program when this happens. You can still