From 42fe7bf352c10b56ec4c53cd966bb819a81966c3 Mon Sep 17 00:00:00 2001
From: Daniel Thompson <daniel@redfelineninja.org.uk>
Date: Thu, 14 May 2020 21:42:16 +0100
Subject: [PATCH] drivers: vibrator: Finalize docstrings

---
 docs/wasp.rst            |  1 -
 wasp/drivers/vibrator.py | 20 ++++++++++++++++++--
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/wasp.rst b/docs/wasp.rst
index 3c3d77e..991950b 100644
--- a/docs/wasp.rst
+++ b/docs/wasp.rst
@@ -56,7 +56,6 @@ Device drivers
 
 .. automodule:: drivers.vibrator
    :members:
-   :undoc-members:
 
 Libraries
 ---------
diff --git a/wasp/drivers/vibrator.py b/wasp/drivers/vibrator.py
index 359e738..bf002b5 100644
--- a/wasp/drivers/vibrator.py
+++ b/wasp/drivers/vibrator.py
@@ -1,13 +1,25 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
 
-# Generic PWM capable vibrator
+"""Generic PWM capable vibration motor driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
 
 import time
 from machine import PWM
 
 class Vibrator(object):
+    """Vibration motor driver.
+
+    .. automethod:: __init__
+    """
     def __init__(self, pin, active_low=False):
+        """Specify the pin and configuration used to operate the motor.
+
+        :param machine.Pin pin: The PWM-capable pin used to driver the
+                                vibration motor.
+        :param bool active_low: Invert the resting state of the motor.
+        """
         pin.value(active_low)
         self.pin = pin
         self.freq = PWM.FREQ_16MHZ
@@ -15,9 +27,13 @@ class Vibrator(object):
         self.active_low = active_low
 
     def pulse(self, duty=25, ms=40):
+        """Briefly pulse the motor.
+
+        :param int duty: Duty cycle, in percent.
+        :param int ms:   Duration, in milliseconds.
+        """
         pwm = PWM(0, self.pin, freq=self.freq, duty=duty, period=self.period)
         pwm.init()
         time.sleep_ms(ms)
         pwm.deinit()
         self.pin.value(self.active_low)
-