RTC: Added javadoc comments

Author: marqdevx

src/utility/RTC/PCF8563T.cpp

@@ -59,8 +59,8 @@ PCF8563TClass::PCF8563TClass()
 
 /**
  *  Start the communication with the RTC
- *  
- *  @return true if the RTC Controller is on the I2C bus, false in case it is not in the bus.
+ *  Initialize I2C (Wire1) bus and check if the chip is connected trhoug sending an ACK on the I2C bus.
+ *  @return true if the RTC Controller is on the I2C bus, false if it is not.
  * 
  */   
 bool PCF8563TClass::begin()
@@ -75,9 +75,9 @@ bool PCF8563TClass::begin()
 }
 
 /**
- *  Set Year number
- *  
- *  @param years  Year's number
+ *  Set Year number's value
+ *  Save an unsigned byte with the Year's value
+ *  @param years  Year's unsigned byte
  */   
 void PCF8563TClass::setYears(uint8_t years) { 
   uint8_t dec = years / 10;
@@ -86,9 +86,9 @@ void PCF8563TClass::setYears(uint8_t years) {
 }
 
 /**
- *  Set Month number
- *  
- *  @param months Month's number (0 to 12)
+ *  Set Month number's value
+ *  Save an unsigned byte with the Month's value
+ *  @param months Month's unsigned byte (0 to 12)
  */   
 void PCF8563TClass::setMonths(uint8_t months) {
   uint8_t offset = 0;
@@ -99,9 +99,9 @@ void PCF8563TClass::setMonths(uint8_t months) {
 }
 
 /**
- *  Set Day number
- *  
- *  @param days day's number
+ *  Set Day number's value
+ *  Save an unsigned byte with the Day's value
+ *  @param days day's unsigned byte
  */   
 void PCF8563TClass::setDays(uint8_t days) {
   uint8_t dec = days / 10;
@@ -110,9 +110,9 @@ void PCF8563TClass::setDays(uint8_t days) {
 }
 
 /**
- *  Set Hour
- *  
- *  @param hours  hour number
+ *  Set Hour(s) number's value
+ *  Save an unsigned byte with the Hour(s) value
+ *  @param hours  hour unsigned byte (0 - 23)
  */   
 void PCF8563TClass::setHours(uint8_t hours) { 
   uint8_t dec = hours / 10;
@@ -121,9 +121,9 @@ void PCF8563TClass::setHours(uint8_t hours) {
 }
 
 /**
- *  Set Minute
- *  
- *  @param minutes  minute number
+ *  Set Minute(s) number's value
+ *  Save an unsigned byte with the Minute(s) value
+ *  @param minutes  minute unsigned byte (0-60)
  */   
 void PCF8563TClass::setMinutes(uint8_t minutes) {
   uint8_t dec = minutes / 10;
@@ -132,9 +132,9 @@ void PCF8563TClass::setMinutes(uint8_t minutes) {
 }
 
 /**
- *  Set Second number
- *  
- *  @param seconds  Second number
+ *  Set Second(s) number's value
+ *  Save an unsigned byte with the Second(s) value
+ *  @param seconds  Second(s) unsigned byte (0-60)
  */   
 void PCF8563TClass::setSeconds(uint8_t seconds) {
   uint8_t dec = seconds / 10;
@@ -143,20 +143,20 @@ void PCF8563TClass::setSeconds(uint8_t seconds) {
 }
 
 /**
- *  Get Year number
- *  
- *  @return number of years
+ *  Get Year(s) number's value
+ *  Get unsigned byte with the Year(s) value
+ *  @return byte with Year(s) value
  */   
 uint8_t PCF8563TClass::getYears() {
   uint8_t years = readByte(PCF8563T_YEARS_REG);
   return (years & 0x0F) + ((years >> 4)*10);
 }
 
 /**
- *  Get Month number
- *  
- *  @return number of month
- */
+ *  Get Month(s) month's value
+ *  Get unsigned byte with the month(s) value
+ *  @return byte with Month(s) value
+ */   
 uint8_t PCF8563TClass::getMonths() {
   uint8_t months = readByte(PCF8563T_MONTHS_REG) & 0x1F;
   if(months > 9) {
@@ -167,47 +167,47 @@ uint8_t PCF8563TClass::getMonths() {
 }
 
 /**
- *  Get Day number
- *  
- *  @return number of days
- */
+ *  Get Day(s) number's value
+ *  Get unsigned byte with the Day(s) value
+ *  @return byte with Day(s) value
+ */   
 uint8_t PCF8563TClass::getDays() {
   uint8_t days = readByte(PCF8563T_DAYS_REG);
   return (days & 0x0F) + ((days >> 4)*10);
 }
 
 /**
- *  Get Hour number
- *  
- *  @return number of hours
- */
+ *  Get Hour(s) number's value
+ *  Get unsigned byte with the Hour(s) value
+ *  @return byte with Hour(s) value
+ */   
 uint8_t PCF8563TClass::getHours() {
   uint8_t hours = readByte(PCF8563T_HOURS_REG) & 0x3F;
   return (hours & 0x0F) + ((hours >> 4)*10);
 }
 
 /**
- *  Get Minute number
- *  
- *  @return number of minutes
- */
+ *  Get Minute(s) number's value
+ *  Get unsigned byte with the Minute(s) value
+ *  @return byte with Minute(s) value
+ */   
 uint8_t PCF8563TClass::getMinutes() {
   uint8_t minutes = (readByte(PCF8563T_MINUTES_REG)) & 0x7F ;
   return (minutes & 0x0F) + ((minutes >> 4)*10);
 }
 
 /**
- *  Get Second number
- *  
- *  @return number of seconds
- */
+ *  Get Second(s) number's value
+ *  Get unsigned byte with the Second(s) value
+ *  @return byte with Second(s) value
+ */   
 uint8_t PCF8563TClass::getSeconds() {
   uint8_t seconds = readByte(PCF8563T_VL_SECONDS_REG) & 0x7F;
   return (seconds & 0x0F) + ((seconds >> 4)*10);
 }
 
 /**
- *  Set time by epoch
+ *  Set time Epoch format
  *  
  */   
 void PCF8563TClass::setEpoch() {
@@ -224,9 +224,10 @@ void PCF8563TClass::setEpoch() {
 }
 
 /**
- *  Set time by epoch
+ *  Set time with Epoch format
+ * 
  *  
- *  @param seconds  number of seconds
+ *  @param seconds  number of seconds (time_t type)
  */    
 void PCF8563TClass::setEpoch(time_t seconds) {
   struct tm time;
@@ -242,8 +243,11 @@ void PCF8563TClass::setEpoch(time_t seconds) {
 }
 
 /**
- *  Set time by epoch
+ *  Set time with Epoch format
  *  
+ *  Convert the input values to Epoch format
+ *  example: Tue, 06 Jul 2021 11:55:27 GMT -> 1625572527
+ * 
  *  @param years  number of years
  *  @param mohths number of months
  *  @param days number of days
@@ -267,9 +271,13 @@ void PCF8563TClass::setEpoch(uint8_t years, uint8_t months, uint8_t days, uint8_
 }
 
 /**
- *  Get epoch number, convert real time to difference between actual time and epoch(Unix time)
- *  
- *  @return number of seconds after Unix time
+ *  Get epoch number
+ *  Convert real time to difference between actual time and Epoch(Unix time)
+ *  Saved into time_t type
+ * 
+ *  example:  1625572527 -> Tue, 06 Jul 2021 11:55:27 GMT 
+ * 
+ *  @return number of seconds after Unix time (time_t type)
  */   
 time_t PCF8563TClass::getEpoch() {
   struct tm time;
@@ -287,15 +295,15 @@ time_t PCF8563TClass::getEpoch() {
 }
 
 /**
- *  Enable alarm mode
+ *  Enable alarm
  *  
  */   
 void PCF8563TClass::enableAlarm() {
   writeByte(PCF8563T_STATUS_2_REG, (readByte(PCF8563T_STATUS_2_REG) & PCF8563T_STATUS_2_CLEAR_INT) | PCF8563T_STATUS_2_AIE_MASK);
 }
 
 /**
- *  Disable alarm mode
+ *  Disable alarm
  *  
  */   
 void PCF8563TClass::disableAlarm() {
@@ -313,8 +321,7 @@ void PCF8563TClass::clearAlarm() {
 /**
  *  Set alarm's minute
  *  
- *  @param minutes  minute number for the Aarm
- *  @return none
+ *  @param minutes minute(s) value for the Alarm (byte type)
  */   
 void PCF8563TClass::setMinuteAlarm(uint8_t minutes) {
   uint8_t dec = minutes / 10;
@@ -334,7 +341,7 @@ void PCF8563TClass::disableMinuteAlarm() {
 /**
  *  Set Alarm's hour
  *  
- *  @param hours  hour number for the Alarm
+ *  @param hours hour(s) value for the Alarm (byte type)
  */   
 void PCF8563TClass::setHourAlarm(uint8_t hours) {
   uint8_t dec = hours / 10;
@@ -354,7 +361,7 @@ void PCF8563TClass::disableHourAlarm() {
 /**
  *  Set Alarm's day
  *  
- *  @param days day number for the Alarm
+ *  @param days day value for the Alarm (byte type)
  */   
 void PCF8563TClass::setDayAlarm(uint8_t days) {
   uint8_t dec = days / 10;