From 2d429e75ce69e77f8c95490ac03881ec9aa0354a Mon Sep 17 00:00:00 2001
From: Marti Bolivar <mbolivar@mit.edu>
Date: Mon, 25 Oct 2010 21:15:28 -0400
Subject: arduino language reference nearing completion, properly CC-BY-SA 3.0
 attributed

---
 source/arduino/highbyte.rst | 46 ++++++++++++++++++++++++++-------------------
 1 file changed, 27 insertions(+), 19 deletions(-)

(limited to 'source/arduino/highbyte.rst')

diff --git a/source/arduino/highbyte.rst b/source/arduino/highbyte.rst
index dc6a1d6..0682391 100644
--- a/source/arduino/highbyte.rst
+++ b/source/arduino/highbyte.rst
@@ -1,42 +1,50 @@
 .. _arduino-highbyte:
 
-highByte()
-==========
-
-Description
------------
-
-Extracts the high-order (leftmost) byte of a word (or the second
-lowest byte of a larger data type).
-
-
+highByte(x)
+===========
 
-Syntax
-------
+.. warning:: This macro is provided for compatibility with Arduino
+   only.  It returns the second-least significant byte in an integral
+   value.  It makes sense to call this the "high" byte on a 16-bit
+   microcontroller like the Atmel chips on Arduinos, but it makes no
+   sense at all on a 32-bit microcontroller like the STM32s in the
+   Maple line.
 
-highByte(x)
+   In short: we provide this so that existing Arduino code works as
+   expected, but **strongly discourage its use** in new programs.
 
+Description
+-----------
 
+(Macro) Extracts the second lowest byte of an integral data type.
 
 Parameters
 ----------
 
-x: a value of any type
+**x**: a value of any integral type.
 
+Returns
+-------
 
+Second lowest byte in **x**.
 
-Returns
+Example
 -------
 
-byte
+::
+
+    int x = 0xDEADBEEF;
+    SerialUSB.println(x, HEX); // prints "BE"
 
+Arduino Compatibility
+---------------------
 
+The Maple version of ``highByte()`` is compatible with Arduino.
 
-See also
+See Also
 --------
 
+-  :ref:`lowByte() <arduino-lowbyte>`
 
--  `lowByte <http://arduino.cc/en/Reference/LowByte>`_\ ()
--  `word <http://arduino.cc/en/Reference/WordCast>`_\ ()
 
 
-- 
cgit v1.2.3