stm32/dac: Add buffering argument to constructor and init() method.

This can be used to select the output buffer behaviour of the DAC.  The
default values are chosen to retain backwards compatibility with existing
behaviour.

Thanks to @peterhinch for the initial idea to add this feature.

1 files changed, 18 insertions, 3 deletions

diff --git a/docs/library/pyb.DAC.rst b/docs/library/pyb.DAC.rst
index fd786b63b..3e236a3da 100644
--- a/docs/library/pyb.DAC.rst
+++ b/docs/library/pyb.DAC.rst
@@ -49,7 +49,7 @@ To output a continuous sine-wave at 12-bit resolution::
 Constructors
 ------------
 
-.. class:: pyb.DAC(port, bits=8)
+.. class:: pyb.DAC(port, bits=8, \*, buffering=None)
 
    Construct a new DAC object.
 
@@ -60,12 +60,27 @@ Constructors
    The maximum value for the write and write_timed methods will be
    2\*\*``bits``-1.
 
+   The *buffering* parameter selects the behaviour of the DAC op-amp output
+   buffer, whose purpose is to reduce the output impedance.  It can be
+   ``None`` to select the default (buffering enabled for :meth:`DAC.noise`,
+   :meth:`DAC.triangle` and :meth:`DAC.write_timed`, and disabled for
+   :meth:`DAC.write`), ``False`` to disable buffering completely, or ``True``
+   to enable output buffering.
+
+   When buffering is enabled the DAC pin can drive loads down to 5KΩ.
+   Otherwise it has an output impedance of 15KΩ maximum: consequently
+   to achieve a 1% accuracy without buffering requires the applied load
+   to be less than 1.5MΩ.  Using the buffer incurs a penalty in accuracy,
+   especially near the extremes of range.
+
 Methods
 -------
 
-.. method:: DAC.init(bits=8)
+.. method:: DAC.init(bits=8, \*, buffering=None)
 
-   Reinitialise the DAC.  ``bits`` can be 8 or 12.
+   Reinitialise the DAC.  *bits* can be 8 or 12.  *buffering* can be
+   ``None``, ``False`` or ``True`; see above constructor for the meaning
+   of this parameter.
 
 .. method:: DAC.deinit()