From 591a344abc1feafa59ed635cd67d4dd2213e24de Mon Sep 17 00:00:00 2001
From: Rhys Weatherley <rhys.weatherley@gmail.com>
Date: Sun, 29 Mar 2015 08:28:01 +1000
Subject: [PATCH] Add missing docs for DS3231RTC

---
 libraries/RTC/DS3231RTC.cpp | 28 ++++++++++++++++++++++++++++
 libraries/RTC/RTC.cpp       | 21 +++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/libraries/RTC/DS3231RTC.cpp b/libraries/RTC/DS3231RTC.cpp
index f52a0528..a4ba0c4a 100644
--- a/libraries/RTC/DS3231RTC.cpp
+++ b/libraries/RTC/DS3231RTC.cpp
@@ -153,6 +153,11 @@ DS3231RTC::DS3231RTC(I2CMaster &bus, uint8_t oneHzPin)
   }
 }
 
+/**
+ * \fn bool DS3231RTC::isRealTime() const
+ * \brief Returns true if the realtime clock is on the I2C bus; false if the time and date are simulated.
+ */
+
 /**
  * \fn bool DS3231RTC::hasUpdates()
  * \brief Returns true if there are updates
@@ -391,6 +396,15 @@ void DS3231RTC::clearAlarm(uint8_t alarmNum) {
   }
 }
 
+/**
+ * \brief Sets the alarm with index \a alarmNum from \a value.
+ *
+ * The \a alarmNum parameter must be between 0 and \ref ALARM_COUNT - 1.
+ *
+ * \return Returns true if the alarm was set; false otherwise.
+ *
+ * \sa writeAlarm()
+ */
 bool DS3231RTC::setAlarm(uint8_t alarmNum, const RTCAlarm* value) {
   if ( _isRealTime ) {
     uint8_t alarm_mask_bits = value->flags;
@@ -582,6 +596,13 @@ bool DS3231RTC::writeRegister(uint8_t reg, uint8_t value) {
   return _bus->endWrite();
 }
 
+/**
+ * \brief Enables a specific alarm.
+ *
+ * \param alarmNum The alarm to enable.
+ *
+ * \sa disableAlarm()
+ */
 void DS3231RTC::enableAlarm(uint8_t alarmNum) {
   uint8_t value = readRegister(DS3231_CONTROL);
 
@@ -594,6 +615,13 @@ void DS3231RTC::enableAlarm(uint8_t alarmNum) {
   writeRegister(DS3231_CONTROL, value);
 }
 
+/**
+ * \brief Disables a specific alarm.
+ *
+ * \param alarmNum The alarm to disable.
+ *
+ * \sa enableAlarm()
+ */
 void DS3231RTC::disableAlarm(uint8_t alarmNum) {
   uint8_t value = readRegister(DS3231_CONTROL);
 
diff --git a/libraries/RTC/RTC.cpp b/libraries/RTC/RTC.cpp
index 4edfa6bf..670078f1 100644
--- a/libraries/RTC/RTC.cpp
+++ b/libraries/RTC/RTC.cpp
@@ -460,6 +460,20 @@ RTC::DayOfWeek RTC::dayOfWeek(const RTCDate *date)
  * \sa RTCTime, RTCDate, RTC
  */
 
+/**
+ * \var RTCAlarm::day
+ * \brief Day of the month for the alarm if not zero.
+ *
+ * \note Currently this field only works with the DS3231RTC class.
+ */
+
+/**
+ * \var RTCAlarm::dow
+ * \brief Day of the week for the alarm if not zero.
+ *
+ * \note Currently this field only works with the DS3231RTC class.
+ */
+
 /**
  * \var RTCAlarm::hour
  * \brief Hour of the day for the alarm (0-23).
@@ -470,6 +484,13 @@ RTC::DayOfWeek RTC::dayOfWeek(const RTCDate *date)
  * \brief Minute of the hour for the alarm (0-59).
  */
 
+/**
+ * \var RTCAlarm::second
+ * \brief Second of the minute for the alarm (0-59).
+ *
+ * \note Currently this field only works with the DS3231RTC class.
+ */
+
 /**
  * \var RTCAlarm::flags
  * \brief Additional flags for the alarm.