From 451f78d156b63c97db60eda438c40fd3740ce347 Mon Sep 17 00:00:00 2001
From: Damien George <damien.p.george@gmail.com>
Date: Sat, 3 May 2014 12:40:53 +0100
Subject: [PATCH] stmhal: Add documentation for RTC class.

---
 stmhal/rtc.c | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/stmhal/rtc.c b/stmhal/rtc.c
index 79e524cab2..28c139db03 100644
--- a/stmhal/rtc.c
+++ b/stmhal/rtc.c
@@ -9,6 +9,12 @@
 #include "runtime.h"
 #include "rtc.h"
 
+/// \moduleref pyb
+/// \class RTC - real time clock
+///
+/// The RTC is and independent clock that keeps track of the date
+/// and time.
+
 RTC_HandleTypeDef RTCHandle;
 
 // rtc_info indicates various things about RTC startup
@@ -159,13 +165,13 @@ void rtc_init(void) {
         // fresh reset; configure RTC Calendar
         RTC_CalendarConfig();
     } else {
-        // RTC was previously set, so leave it alon
+        // RTC was previously set, so leave it alone
         if(__HAL_RCC_GET_FLAG(RCC_FLAG_PORRST) != RESET) {
-            // power on reset occured
+            // power on reset occurred
             rtc_info |= 0x10000;
         }
         if(__HAL_RCC_GET_FLAG(RCC_FLAG_PINRST) != RESET) {
-            // external reset occured
+            // external reset occurred
             rtc_info |= 0x20000;
         }
         // Clear source Reset Flag
@@ -213,6 +219,8 @@ typedef struct _pyb_rtc_obj_t {
 
 STATIC const pyb_rtc_obj_t pyb_rtc_obj = {{&pyb_rtc_type}};
 
+/// \classmethod \constructor()
+/// Create an RTC object.
 STATIC mp_obj_t pyb_rtc_make_new(mp_obj_t type_in, uint n_args, uint n_kw, const mp_obj_t *args) {
     // check arguments
     mp_arg_check_num(n_args, n_kw, 0, 0, false);
@@ -221,11 +229,32 @@ STATIC mp_obj_t pyb_rtc_make_new(mp_obj_t type_in, uint n_args, uint n_kw, const
     return (mp_obj_t)&pyb_rtc_obj;
 }
 
+/// \method info()
+/// Get information about the startup time and reset source.
+///
+///  - The lower 0xffff are the number of milliseconds the RTC took to
+///    start up.
+///  - Bit 0x10000 is set if a power-on reset occurred.
+///  - Bit 0x20000 is set if an external reset occurred
 mp_obj_t pyb_rtc_info(mp_obj_t self_in) {
     return mp_obj_new_int(rtc_info);
 }
 MP_DEFINE_CONST_FUN_OBJ_1(pyb_rtc_info_obj, pyb_rtc_info);
 
+/// \method datetime([datetimetuple])
+/// Get or set the date and time of the RTC.
+///
+/// With no arguments, this method returns an 8-tuple with the current
+/// date and time.  With 1 argument (being an 8-tuple) it sets the date
+/// and time.
+///
+/// The 8-tuple has the following format:
+///
+///     (year, month, day, weekday, hours, minutes, seconds, subseconds)
+///
+/// `weekday` is 1-7 for Monday through Sunday.
+///
+/// `subseconds` is 0-59.
 mp_obj_t pyb_rtc_datetime(uint n_args, const mp_obj_t *args) {
     if (n_args == 1) {
         // get date and time