stmhal: Start of documentation for modos and modtime.

stmhal/modos.c

@@ -41,6 +41,19 @@
 #include "sdcard.h"
 #include "portmodules.h"
 
+/// \module os - basic "operating system" services
+///
+/// The `os` module contains functions for filesystem access and `urandom`.
+///
+/// The filesystem has `/` as the root directory, and the available physical
+/// drives are accessible from here.  They are currently:
+///
+///     /flash      -- the internal flash filesystem
+///     /sd         -- the SD card (if it exists)
+///
+/// On boot up, the current directory is `/flash` if no SD card is inserted,
+/// otherwise it is `/sd`.
+
 #if _USE_LFN
 static char lfn[_MAX_LFN + 1];   /* Buffer to store the LFN */
 #endif
@@ -54,6 +67,8 @@ STATIC bool sd_in_root(void) {
 #endif
 }
 
+/// \function chdir(path)
+/// Change current directory.
 STATIC mp_obj_t os_chdir(mp_obj_t path_in) {
     const char *path;
     path = mp_obj_str_get_str(path_in);
@@ -73,6 +88,8 @@ STATIC mp_obj_t os_chdir(mp_obj_t path_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_chdir_obj, os_chdir);
 
+/// \function getcwd()
+/// Get the current directory.
 STATIC mp_obj_t os_getcwd(void) {
     char buf[MICROPY_ALLOC_PATH_MAX + 1];
     FRESULT res = f_getcwd(buf, sizeof buf);
@@ -85,6 +102,8 @@ STATIC mp_obj_t os_getcwd(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_getcwd_obj, os_getcwd);
 
+/// \function listdir([dir])
+/// With no argument, list the current directory.  Otherwise list the given directory.
 STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) {
     bool is_str_type = true;
     const char *path;
@@ -161,6 +180,8 @@ STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(os_listdir_obj, 0, 1, os_listdir);
 
+/// \function mkdir(path)
+/// Create a new directory.
 STATIC mp_obj_t os_mkdir(mp_obj_t path_o) {
     const char *path = mp_obj_str_get_str(path_o);
     FRESULT res = f_mkdir(path);
@@ -176,6 +197,8 @@ STATIC mp_obj_t os_mkdir(mp_obj_t path_o) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_mkdir_obj, os_mkdir);
 
+/// \function remove(path)
+/// Remove a file.
 STATIC mp_obj_t os_remove(mp_obj_t path_o) {
     const char *path = mp_obj_str_get_str(path_o);
     // TODO check that path is actually a file before trying to unlink it
@@ -189,6 +212,8 @@ STATIC mp_obj_t os_remove(mp_obj_t path_o) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_remove_obj, os_remove);
 
+/// \function rmdir(path)
+/// Remove a directory.
 STATIC mp_obj_t os_rmdir(mp_obj_t path_o) {
     const char *path = mp_obj_str_get_str(path_o);
     // TODO check that path is actually a directory before trying to unlink it
@@ -217,6 +242,8 @@ STATIC bool path_equal(const char *path, const char *path_canonical) {
     return *path == '\0';
 }
 
+/// \function stat(path)
+/// Get the status of a file or directory.
 STATIC mp_obj_t os_stat(mp_obj_t path_in) {
     const char *path = mp_obj_str_get_str(path_in);
 
@@ -278,6 +305,8 @@ error:
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_stat_obj, os_stat);
 
+/// \function sync()
+/// Sync all filesystems.
 STATIC mp_obj_t os_sync(void) {
     storage_flush();
     return mp_const_none;
@@ -285,6 +314,9 @@ STATIC mp_obj_t os_sync(void) {
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync);
 
 #if MICROPY_HW_ENABLE_RNG
+/// \function urandom(n)
+/// Return a bytes object with n random bytes, generated by the hardware
+/// random number generator.
 STATIC mp_obj_t os_urandom(mp_obj_t num) {
     mp_int_t n = mp_obj_get_int(num);
     byte *data;
@@ -311,6 +343,7 @@ STATIC const mp_map_elem_t os_module_globals_table[] = {
 
     { MP_OBJ_NEW_QSTR(MP_QSTR_sync), (mp_obj_t)&os_sync_obj },
 
+    /// \constant sep - separation character used in paths
     { MP_OBJ_NEW_QSTR(MP_QSTR_sep), MP_OBJ_NEW_QSTR(MP_QSTR__slash_) },
 
 #if MICROPY_HW_ENABLE_RNG

stmhal/modtime.c

@@ -34,6 +34,11 @@
 #include "portmodules.h"
 #include "rtc.h"
 
+/// \module time - time related functions
+///
+/// The `time` module provides functions for getting the current time and date,
+/// and for sleeping.
+
 STATIC const uint16_t days_since_jan1[]= { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 };
 
 STATIC bool is_leap_year(mp_uint_t year) {
@@ -64,8 +69,9 @@ mp_uint_t mod_time_seconds_since_2000(mp_uint_t year, mp_uint_t month, mp_uint_t
         + (year - 2000) * 31536000;
 }
 
-// returns time stored in RTC as: (year, month, date, hour, minute, second, weekday)
+/// \function localtime()
-// weekday is 0-6 for Mon-Sun
+/// Returns time stored in RTC as: (year, month, date, hour, minute, second, weekday).
+/// Weekday is 0-6 for Mon-Sun.
 STATIC mp_obj_t time_localtime(void) {
     // get date and time
     // note: need to call get time then get date to correctly access the registers
@@ -87,6 +93,9 @@ STATIC mp_obj_t time_localtime(void) {
 }
 MP_DEFINE_CONST_FUN_OBJ_0(time_localtime_obj, time_localtime);
 
+/// \function sleep(seconds)
+/// Sleep for the given number of seconds.  Seconds can be a floating-point number to
+/// sleep for a fractional number of seconds.
 STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) {
 #if MICROPY_PY_BUILTINS_FLOAT
     if (MP_OBJ_IS_INT(seconds_o)) {
@@ -101,7 +110,8 @@ STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) {
 }
 MP_DEFINE_CONST_FUN_OBJ_1(time_sleep_obj, time_sleep);
 
-// returns the number of seconds, as an integer, since 1/1/2000
+/// \function time()
+/// Returns the number of seconds, as an integer, since 1/1/2000.
 STATIC mp_obj_t time_time(void) {
     // get date and time
     // note: need to call get time then get date to correctly access the registers

stmhal/pin.c

@@ -589,7 +589,7 @@ STATIC mp_obj_t pin_af_index(mp_obj_t self_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_index_obj, pin_af_index);
 
-/// \method index()
+/// \method name()
 /// Return the name of the alternate function.
 STATIC mp_obj_t pin_af_name(mp_obj_t self_in) {
     pin_af_obj_t *af = self_in;
@@ -597,7 +597,7 @@ STATIC mp_obj_t pin_af_name(mp_obj_t self_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_name_obj, pin_af_name);
 
-/// \method index()
+/// \method reg()
 /// Return the base register associated with the peripheral assigned to this
 /// alternate function. For example, if the alternate function were TIM2_CH3
 /// this would return stm.TIM2