Mainly formatting already existing comments to Doxygen format.

Author: Jasper Klein

Ports.h

@@ -223,11 +223,11 @@ class DeviceI2C {
         { addr = me << 1; }
 };
 
-// The millisecond timer can be used for timeouts up to 60000 milliseconds.
-// Setting the timeout to zero disables the timer.
-//
-// for periodic timeouts, poll the timer object with "if (timer.poll(123)) ..."
-// for one-shot timeouts, call "timer.set(123)" and poll as "if (timer.poll())"
+/// The millisecond timer can be used for timeouts up to 60000 milliseconds.
+/// Setting the timeout to zero disables the timer.
+///
+/// for periodic timeouts, poll the timer object with "if (timer.poll(123)) ..."
+/// for one-shot timeouts, call "timer.set(123)" and poll as "if (timer.poll())"
 
 class MilliTimer {
     word next;
@@ -241,47 +241,47 @@ class MilliTimer {
     void set(word ms);
 };
 
-// Low-power utility code using the Watchdog Timer (WDT). Requires a WDT interrupt handler, e.g.
-// EMPTY_INTERRUPT(WDT_vect);
+/// Low-power utility code using the Watchdog Timer (WDT). Requires a WDT interrupt handler, e.g.
+/// EMPTY_INTERRUPT(WDT_vect);
 class Sleepy {
 public:
-    // start the watchdog timer (or disable it if mode < 0)
+    /// start the watchdog timer (or disable it if mode < 0)
     static void watchdogInterrupts (char mode);
 
-    // enter low-power mode, wake up with watchdog, INT0/1, or pin-change
+    /// enter low-power mode, wake up with watchdog, INT0/1, or pin-change
     static void powerDown ();
 
-    // spend some time in low-power mode, the timing is only approximate
-    // returns 1 if all went normally, or 0 if some other interrupt occurred
+    /// spend some time in low-power mode, the timing is only approximate
+    /// returns 1 if all went normally, or 0 if some other interrupt occurred
     static byte loseSomeTime (word msecs);
 
-    // this must be called from your watchdog interrupt code
+    /// this must be called from your watchdog interrupt code
     static void watchdogEvent();
 };
 
-// simple task scheduler for times up to 6000 seconds
+/// simple task scheduler for times up to 6000 seconds
 class Scheduler {
     word* tasks;
     word remaining;
     byte maxTasks;
     MilliTimer ms100;
 public:
-    // initialize for a specified maximum number of tasks
+    /// initialize for a specified maximum number of tasks
     Scheduler (byte max);
     Scheduler (word* buf, byte max);
 
-    // return next task to run, -1 if there are none ready to run, but there are tasks waiting, or -2 if there are no tasks waiting (i.e. all are idle)
+    /// return next task to run, -1 if there are none ready to run, but there are tasks waiting, or -2 if there are no tasks waiting (i.e. all are idle)
     char poll();
-    // same as poll, but wait for event in power-down mode.
-    // Uses Sleepy::loseSomeTime() - see comments there re requiring the watchdog timer. 
+    /// same as poll, but wait for event in power-down mode.
+    /// Uses Sleepy::loseSomeTime() - see comments there re requiring the watchdog timer. 
     char pollWaiting();
 
-    // set a task timer, in tenths of seconds
+    /// set a task timer, in tenths of seconds
     void timer(byte task, word tenths);
-    // cancel a task timer
+    /// cancel a task timer
     void cancel(byte task);
 
-    // return true if a task timer is not running
+    /// return true if a task timer is not running
     byte idle(byte task) { return tasks[task] == ~0; }
 };
 
@@ -307,7 +307,7 @@ class BlinkPlug : public Port {
     byte buttonCheck();
 };
 
-// interface for the Memory Plug - see http://jeelabs.org/mp1
+///Interface for the Memory Plug - see http://jeelabs.org/mp1
 class MemoryPlug : public DeviceI2C {
     uint32_t nextSave;
 public:
@@ -354,7 +354,7 @@ class UartPlug : public Print {
     virtual WRITE_RESULT write(byte);
 };
 
-// interface for the Dimmer Plug - see http://jeelabs.org/dp1
+/// Interface for the Dimmer Plug - see http://jeelabs.org/dp1
 class DimmerPlug : public DeviceI2C {
 public:
     enum {
@@ -467,7 +467,7 @@ class InfraredPlug : public Port {
     void send(const uint8_t* data, uint16_t bits);
 };
 
-// interface for the Heading Board - see http://jeelabs.org/hb1
+/// Interface for the Heading Board - see http://jeelabs.org/hb1
 class HeadingBoard : public PortI2C {
     DeviceI2C eeprom, adc, compass;
     Port aux;
@@ -489,8 +489,8 @@ class HeadingBoard : public PortI2C {
     void heading(int& xaxis, int& yaxis);
 };
 
-// interface for the Modern Device 3-axis Compass board
-// see http://shop.moderndevice.com/products/3-axis-compass
+/// Interface for the Modern Device 3-axis Compass board
+/// see http://shop.moderndevice.com/products/3-axis-compass
 class CompassBoard : public DeviceI2C {
     int read2 (byte last);
 public:
@@ -499,7 +499,7 @@ class CompassBoard : public DeviceI2C {
     float heading();
 };
 
-// interface for the Proximity Plug - see http://jeelabs.org/yp1
+/// Interface for the Proximity Plug - see http://jeelabs.org/yp1
 class ProximityPlug : public DeviceI2C {
 public:
     enum {
@@ -518,33 +518,33 @@ class ProximityPlug : public DeviceI2C {
     byte getReg(byte reg) const;
 };
 
-// interface for the Analog Plug - see http://jeelabs.org/ap2
+/// Interface for the Analog Plug - see http://jeelabs.org/ap2
 class AnalogPlug : public DeviceI2C {
   byte config;
 public:
   AnalogPlug (const PortI2C& port, byte addr =0x69)
     : DeviceI2C (port, addr), config (0x1C) {}
 
-  // default mode is channel 1, continuous, 18-bit, gain x1
+  /// Default mode is channel 1, continuous, 18-bit, gain x1
   void begin (byte mode =0x1C);
-  // select a channel (1..4), must wait to read it out (up to 270 ms for 18-bit)
+  /// Select a channel (1..4), must wait to read it out (up to 270 ms for 18-bit)
   void select (byte channel);
-  // read out 4 bytes, caller will need to shift out the irrelevant lower bits
+  /// Read out 4 bytes, caller will need to shift out the irrelevant lower bits
   long reading ();
 };
 
-// interface for the DHT11 and DHT22 sensors, does not use floating point
+/// Interface for the DHT11 and DHT22 sensors, does not use floating point
 class DHTxx {
   byte pin;
 public:
   DHTxx (byte pinNum);
-  // results are returned in tenths of a degree and percent, respectively
+  /// Results are returned in tenths of a degree and percent, respectively
   bool reading (int& temp, int &humi);
 };
 
 #ifdef Stream_h // only available in recent Arduino IDE versions
 
-// simple parser for input data and one-letter commands
+/// Simple parser for input data and one-letter commands
 class InputParser {
 public:
     typedef struct {
@@ -553,14 +553,14 @@ class InputParser {
         void (*fun)();  // code to call for this command
     } Commands;
 
-    // set up with a buffer of specified size
+    /// Set up with a buffer of specified size
     InputParser (byte size, Commands PROGMEM*, Stream& =Serial);
     InputParser (byte* buf, byte size, Commands PROGMEM*, Stream& =Serial);
 
-    // number of data bytes
+    /// Number of data bytes
     byte count() { return fill; }
 
-    // call this frequently to check for incoming data
+    /// Call this frequently to check for incoming data
     void poll();
 
     InputParser& operator >> (char& v)      { return get(&v, 1); }

PortsBMP085.cpp

@@ -32,6 +32,7 @@ int32_t BMP085::getResult(uint8_t type) {
     return meas[type];
 }
 
+///Call this during setup() if you want to use calculate() later on.
 void BMP085::getCalibData() {
     readFromReg(0xAA);
     ac1 = readWord(0);
@@ -47,6 +48,10 @@ void BMP085::getCalibData() {
     md = readWord(1);
 }
 
+/**Calculate the temperature and pressure based on the values stored by the last call to measure().
+ * @param tval Variable temperature value.
+ * @param pval Raw pressure value.
+ */
 void BMP085::calculate(int16_t& tval, int32_t& pval) const {
     int32_t ut = meas[TEMP], up = meas[PRES];
     int32_t x1, x2, x3, b3, b5, b6, p;

PortsBMP085.h

@@ -1,4 +1,4 @@
-// Port library interface to BMP085 sensors connected via I2C
+/// Port library interface to BMP085 sensors connected via I2C - see: http://jeelabs.net/projects/hardware/wiki/pp1
 // 2009-02-17 <[email protected]> http://opensource.org/licenses/mit-license.php
 
 class BMP085 : public DeviceI2C {
@@ -14,15 +14,20 @@ class BMP085 : public DeviceI2C {
     enum { TEMP, PRES };
     int32_t meas[2];
     uint8_t oss;
-    
+
+    ///Constructor for BMP085 class. @param osrs 0..3 Oversampling setting.
     BMP085 (const PortI2C& p, uint8_t osrs =0)
         : DeviceI2C (p, 0x77), oss (osrs) {}
-        
+
+    ///Set the oversampling setting for the high resolution mode. @param osrs 0..3.
     void setOverSampling(uint8_t osrs) { oss = osrs; }
-    
+
+    ///Start a measurement. @param type BMP::TEMP for temperature or BMP::PRES for pressure.
     uint8_t startMeas(uint8_t type) const;
+    ///Get the results from the last measurement. @param type BMP::TEMP for temperature or BMP::PRES for pressure.
     int32_t getResult(uint8_t type);
-    
+
+    ///Take a measurement. @param type BMP::TEMP for temperature or BMP::PRES for pressure.
     int32_t measure(uint8_t type)
         { delay(startMeas(type)); return getResult(type); }
 

PortsLCD.cpp

@@ -103,7 +103,7 @@ void LiquidCrystalBase::setCursor(byte col, byte row)
   command(LCD_SETDDRAMADDR | (col + row_offsets[row]));
 }
 
-// Turn the display on/off (quickly)
+/// Turn the display on/off (quickly)
 void LiquidCrystalBase::noDisplay() {
   _displaycontrol &= ~LCD_DISPLAYON;
   command(LCD_DISPLAYCONTROL | _displaycontrol);
@@ -113,7 +113,7 @@ void LiquidCrystalBase::display() {
   command(LCD_DISPLAYCONTROL | _displaycontrol);
 }
 
-// Turns the underline cursor on/off
+/// Turns the underline cursor on/off
 void LiquidCrystalBase::noCursor() {
   _displaycontrol &= ~LCD_CURSORON;
   command(LCD_DISPLAYCONTROL | _displaycontrol);
@@ -123,7 +123,7 @@ void LiquidCrystalBase::cursor() {
   command(LCD_DISPLAYCONTROL | _displaycontrol);
 }
 
-// Turn on and off the blinking cursor
+/// Turn on and off the blinking cursor
 void LiquidCrystalBase::noBlink() {
   _displaycontrol &= ~LCD_BLINKON;
   command(LCD_DISPLAYCONTROL | _displaycontrol);
@@ -133,40 +133,40 @@ void LiquidCrystalBase::blink() {
   command(LCD_DISPLAYCONTROL | _displaycontrol);
 }
 
-// These commands scroll the display without changing the RAM
+/// These commands scroll the display without changing the RAM
 void LiquidCrystalBase::scrollDisplayLeft(void) {
   command(LCD_CURSORSHIFT | LCD_DISPLAYMOVE | LCD_MOVELEFT);
 }
 void LiquidCrystalBase::scrollDisplayRight(void) {
   command(LCD_CURSORSHIFT | LCD_DISPLAYMOVE | LCD_MOVERIGHT);
 }
 
-// This is for text that flows Left to Right
+/// This is for text that flows Left to Right
 void LiquidCrystalBase::leftToRight(void) {
   _displaymode |= LCD_ENTRYLEFT;
   command(LCD_ENTRYMODESET | _displaymode);
 }
 
-// This is for text that flows Right to Left
+/// This is for text that flows Right to Left
 void LiquidCrystalBase::rightToLeft(void) {
   _displaymode &= ~LCD_ENTRYLEFT;
   command(LCD_ENTRYMODESET | _displaymode);
 }
 
-// This will 'right justify' text from the cursor
+/// This will 'right justify' text from the cursor
 void LiquidCrystalBase::autoscroll(void) {
   _displaymode |= LCD_ENTRYSHIFTINCREMENT;
   command(LCD_ENTRYMODESET | _displaymode);
 }
 
-// This will 'left justify' text from the cursor
+/// This will 'left justify' text from the cursor
 void LiquidCrystalBase::noAutoscroll(void) {
   _displaymode &= ~LCD_ENTRYSHIFTINCREMENT;
   command(LCD_ENTRYMODESET | _displaymode);
 }
 
-// Allows us to fill the first 8 CGRAM locations
-// with custom characters
+/// Allows us to fill the first 8 CGRAM locations
+/// with custom characters
 void LiquidCrystalBase::createChar(byte location, byte charmap[]) {
   location &= 0x7; // we only have 8 locations 0-7
   command(LCD_SETCGRAMADDR | (location << 3));
@@ -277,7 +277,7 @@ void LiquidCrystal::config() {
   }
 }
 
-// write either command or data, with automatic 4/8-bit selection
+/// write either command or data, with automatic 4/8-bit selection
 void LiquidCrystal::send(byte value, byte mode) {
   digitalWrite(_rs_pin, mode);
 
@@ -363,7 +363,7 @@ void LiquidCrystalI2C::config() {
   backlight(); // start with backlight on
 }
 
-// write either command or data, with automatic 4/8-bit selection
+/// write either command or data, with automatic 4/8-bit selection
 void LiquidCrystalI2C::send(byte value, byte mode) {
   if (mode != 0)
     mode = MCP_REGSEL;

PortsLCD.h

@@ -48,9 +48,9 @@
 #define LCD_5x10DOTS 0x04
 #define LCD_5x8DOTS 0x00
 
-// this class defines all the basic functionality needed to drive an LCD display
-// it is an incomplete (abstract) base class, which needs to be extended for use
-// see the LiquidCrystal and LiquidCrystalI2C classes for two usable versions
+/// this class defines all the basic functionality needed to drive an LCD display
+/// it is an incomplete (abstract) base class, which needs to be extended for use
+/// see the LiquidCrystal and LiquidCrystalI2C classes for two usable versions
 
 class LiquidCrystalBase : public Print {
 public:
@@ -90,10 +90,10 @@ class LiquidCrystalBase : public Print {
   byte _numlines,_currline;
 };
 
-// This class can be used to create an object with drives an LCD through many
-// different I/O pins, connected to the display in parallel - it is equivalent
-// to the LiquidCrystal class defined in the Arduino, but has be adjusted to
-// work with the above LiquidCrystalBase instead.
+/// This class can be used to create an object with drives an LCD through many
+/// different I/O pins, connected to the display in parallel - it is equivalent
+/// to the LiquidCrystal class defined in the Arduino, but has be adjusted to
+/// work with the above LiquidCrystalBase instead.
 
 class LiquidCrystal : public LiquidCrystalBase {
 public:
@@ -122,9 +122,9 @@ class LiquidCrystal : public LiquidCrystalBase {
   byte _data_pins[8];
 };
 
-// This class allows driving an LCD connected via I2C using an LCD Plug, which
-// is in turn based on an MCP23008 I2C I/O expander chip and some other parts.
-// The available functions include all those of the LiquidCrystal class.
+/// This class allows driving an LCD connected via I2C using an LCD Plug, which
+/// is in turn based on an MCP23008 I2C I/O expander chip and some other parts.
+/// The available functions include all those of the LiquidCrystal class.
 
 class LiquidCrystalI2C : public LiquidCrystalBase {
   DeviceI2C device;