7 files changed, 44 insertions, 16 deletions
diff --git a/shared-bindings/_bleio/Service.c b/shared-bindings/_bleio/Service.c
index 52dea592e..3e1ad7088 100644
--- a/shared-bindings/_bleio/Service.c
+++ b/shared-bindings/_bleio/Service.c
@@ -41,7 +41,7 @@
 //|
 //| .. class:: Service(uuid, *, secondary=False)
 //|
-//|   Create a new Service identitied by the specified UUID. It can be accessed by all
+//|   Create a new Service identified by the specified UUID. It can be accessed by all
 //|   connections. This is known as a Service server. Client Service objects are created via
 //|   `Connection.discover_remote_services`.
 //|
diff --git a/shared-bindings/_pixelbuf/__init__.c b/shared-bindings/_pixelbuf/__init__.c
index 48b9f1cef..eb0cb2984 100644
--- a/shared-bindings/_pixelbuf/__init__.c
+++ b/shared-bindings/_pixelbuf/__init__.c
@@ -55,7 +55,7 @@
 
 //| .. class:: ByteOrder()
 //|
-//|   Classes representing byteorders for circuitpython
+//|   Classes representing byteorders for CircuitPython
 
 
 //|   .. attribute:: bpp
@@ -284,7 +284,7 @@ PIXELBUF_BYTEORDER(LBRG, 4, 3, 1, 2, 0, false, true)
 //|    * **bpp** 4
 //|    * **has_luminosity** True
 //|
-//|    Actual format commonly used by DotStar (5 bit luninance value)
+//|    Actual format commonly used by DotStar (5 bit luminance value)
 PIXELBUF_BYTEORDER(LBGR, 4, 3, 2, 1, 0, false, true)
 
 STATIC const mp_rom_map_elem_t pixelbuf_module_globals_table[] = {
diff --git a/shared-bindings/audiobusio/I2SOut.c b/shared-bindings/audiobusio/I2SOut.c
index 2cd2b6728..81383c777 100644
--- a/shared-bindings/audiobusio/I2SOut.c
+++ b/shared-bindings/audiobusio/I2SOut.c
@@ -62,7 +62,7 @@
 //|     import time
 //|     import math
 //|
-//|     # Generate one period of sine wav.
+//|     # Generate one period of sine wave.
 //|     length = 8000 // 440
 //|     sine_wave = array.array("H", [0] * length)
 //|     for i in range(length):
diff --git a/shared-bindings/audioio/__init__.c b/shared-bindings/audioio/__init__.c
index 7fa37d5c5..02a5fe1ee 100644
--- a/shared-bindings/audioio/__init__.c
+++ b/shared-bindings/audioio/__init__.c
@@ -68,7 +68,7 @@
 //|
 //| For compatibility with CircuitPython 4.x, some builds allow the items in
 //| `audiocore` to be imported from `audioio`.  This will be removed for all
-//| boards in a future build of CicuitPython.
+//| boards in a future build of CircuitPython.
 //|
 
 STATIC const mp_rom_map_elem_t audioio_module_globals_table[] = {
diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c
index 40981e0a8..53b88c61a 100644
--- a/shared-bindings/pulseio/PWMOut.c
+++ b/shared-bindings/pulseio/PWMOut.c
@@ -162,6 +162,11 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pulseio_pwmout___exit___obj, 4, 4, pu
 //|      16 bit value that dictates how much of one cycle is high (1) versus low
 //|      (0). 0xffff will always be high, 0 will always be low and 0x7fff will
 //|      be half high and then half low.
+//|
+//|      Depending on how PWM is implemented on a specific board, the internal
+//|      representation for duty cycle might have less than 16 bits of resolution.
+//|      Reading this property will return the value from the internal representation,
+//|      so it may differ from the value set.
 STATIC mp_obj_t pulseio_pwmout_obj_get_duty_cycle(mp_obj_t self_in) {
     pulseio_pwmout_obj_t *self = MP_OBJ_TO_PTR(self_in);
     check_for_deinit(self);
@@ -193,6 +198,12 @@ const mp_obj_property_t pulseio_pwmout_duty_cycle_obj = {
 //|     32 bit value that dictates the PWM frequency in Hertz (cycles per
 //|     second). Only writeable when constructed with ``variable_frequency=True``.
 //|
+//|     Depending on how PWM is implemented on a specific board, the internal value
+//|     for the PWM's duty cycle may need to be recalculated when the frequency
+//|     changes. In these cases, the duty cycle is automatically recalculated
+//|     from the original duty cycle value. This should happen without any need
+//|     to manually re-set the duty cycle.
+//|
 STATIC mp_obj_t pulseio_pwmout_obj_get_frequency(mp_obj_t self_in) {
     pulseio_pwmout_obj_t *self = MP_OBJ_TO_PTR(self_in);
     check_for_deinit(self);
diff --git a/shared-bindings/rtc/RTC.c b/shared-bindings/rtc/RTC.c
index 17dccdb03..3ff09a4ec 100644
--- a/shared-bindings/rtc/RTC.c
+++ b/shared-bindings/rtc/RTC.c
@@ -57,7 +57,23 @@ STATIC mp_obj_t rtc_rtc_make_new(const mp_obj_type_t *type, size_t n_args, const
 
 //|   .. attribute:: datetime
 //|
-//|       The date and time of the RTC.
+//|       The current date and time of the RTC as a `time.struct_time`.
+//|
+//|       This must be set to the current date and time whenever the board loses power::
+//|
+//|         import rtc
+//|         import time
+//|
+//|         r = rtc.RTC()
+//|         r.datetime = rtctime.struct_time((2019, 5, 29, 15, 14, 15, 0, -1, -1))
+//|
+//|
+//|       Once set, the RTC will automatically update this value as time passes. You can read this
+//|       property to get a snapshot of the current time::
+//|
+//|         current_time = r.datetime
+//|         print(current_time)
+//|         # struct_time(tm_year=2019, tm_month=5, ...)
 //|
 STATIC mp_obj_t rtc_rtc_obj_get_datetime(mp_obj_t self_in) {
     timeutils_struct_time_t tm;
@@ -83,9 +99,10 @@ const mp_obj_property_t rtc_rtc_datetime_obj = {
 
 //|   .. attribute:: calibration
 //|
-//|     The RTC calibration value.
+//|     The RTC calibration value as an `int`.
+//|
 //|     A positive value speeds up the clock and a negative value slows it down.
-//|     Range and value is hardware specific, but one step is often approx. 1 ppm.
+//|     Range and value is hardware specific, but one step is often approximately 1 ppm.
 //|
 STATIC mp_obj_t rtc_rtc_obj_get_calibration(mp_obj_t self_in) {
     int calibration = common_hal_rtc_get_calibration();
diff --git a/shared-bindings/rtc/__init__.c b/shared-bindings/rtc/__init__.c
index ac67a7131..22eda9b66 100644
--- a/shared-bindings/rtc/__init__.c
+++ b/shared-bindings/rtc/__init__.c
@@ -36,12 +36,13 @@
 //|
 //| .. module:: rtc
 //|   :synopsis: Real Time Clock
-//|   :platform: SAMD21
+//|   :platform: SAMD21, SAMD51, nRF52
 //|
-//| The `rtc` module provides support for a Real Time Clock.
-//| It also backs the `time.time()` and `time.localtime()` functions using the onboard RTC if present.
+//| The `rtc` module provides support for a Real Time Clock. You can access and manage the
+//| RTC using :class:`rtc.RTC`. It also backs the :func:`time.time` and :func:`time.localtime`
+//| functions using the onboard RTC if present.
 //|
-//| Libraries
+//| Classes
 //|
 //| .. toctree::
 //|     :maxdepth: 3
@@ -63,10 +64,9 @@ mp_obj_t rtc_get_time_source_time(void) {
 
 //| .. function:: set_time_source(rtc)
 //|
-//|   Sets the rtc time source used by time.localtime().
-//|   The default is `rtc.RTC()`.
-//|
-//|   Example usage::
+//|   Sets the RTC time source used by :func:`time.localtime`.
+//|   The default is :class:`rtc.RTC`, but it's useful to use this to override the
+//|   time source for testing purposes. For example::
 //|
 //|     import rtc
 //|     import time