From 759e8a68a9510d3904ee734074137731bf7b4a89 Mon Sep 17 00:00:00 2001
From: Ian Harvey <noone@example.com>
Date: Thu, 24 Dec 2015 18:20:09 +0000
Subject: [PATCH] Tidy up documentation, add scanning example code

---
 docs/notifications.rst |  2 +-
 docs/peripheral.rst    |  8 ++++----
 docs/scanner.rst       | 40 +++++++++++++++++++++++++++++++++++++++-
 3 files changed, 44 insertions(+), 6 deletions(-)

diff --git a/docs/notifications.rst b/docs/notifications.rst
index 94eeedef..2ea9955e 100644
--- a/docs/notifications.rst
+++ b/docs/notifications.rst
@@ -7,7 +7,7 @@ In ``bluepy``, notifications are processed by creating a "delegate" object and
 registering it with the ``Peripheral``. A method in the delegate is called whenever
 a notification is received from the peripheral, as shown below:
 
-.. function:: handleNotification(cHandle, data):
+.. function:: handleNotification(cHandle, data)
 
     Called when a notification has been received from a ``Peripheral``. Normally
     you will call the peripheral's ``waitForNotifications()`` method to allow this,
diff --git a/docs/peripheral.rst b/docs/peripheral.rst
index 625ae3ae..d7447fae 100644
--- a/docs/peripheral.rst
+++ b/docs/peripheral.rst
@@ -11,8 +11,8 @@ Constructor
 .. function:: Peripheral([deviceAddress=None, [addrType=ADDR_TYPE_PUBLIC [, iface=None]]])
 
    If *deviceAddress* is not ``None``, creates a ``Peripheral`` object and makes a connection
-   to the device indicated by *deviceAddress* (which should be a string comprising six hex
-   bytes separated by colons, e.g. ``"11:22:33:ab:cd:ed"``).
+   to the device indicated by *deviceAddress*. *deviceAddress* should be a string comprising six hex
+   bytes separated by colons, e.g. ``"11:22:33:ab:cd:ed"``.
    
    If *deviceAddress* is ``None``, creates an un-connected ``Peripheral`` object. You must call the ``connect()`` method on this object (passing it a device address) before it will be usable.
    
@@ -22,7 +22,7 @@ Constructor
    details.
    
    The *iface* parameter allows the Bluetooth interface on which to make the connection to be set.
-   On Linux, ``0`` means */dev/hci0*, ``1`` means */dev/hci1* and so on.
+   On Linux, 0 means */dev/hci0*, 1 means */dev/hci1* and so on.
 
    *deviceAddress* may also be a ``ScanEntry`` object. In this case the device address,
    address type, and interface number are all taken from the ``ScanEntry`` values, and 
@@ -119,7 +119,7 @@ Instance Methods
     If *withResponse* is true, will await confirmation that the write was successful
     from the device.
     
-.. function:: readCharacteristic(handle):
+.. function:: readCharacteristic(handle)
 
     Reads the current value of the characteristic identified by *handle*. This is
     useful if you know the handle for the characteristic but do not have a suitable
diff --git a/docs/scanner.rst b/docs/scanner.rst
index 14a86eb3..4bec2b78 100644
--- a/docs/scanner.rst
+++ b/docs/scanner.rst
@@ -38,7 +38,7 @@ Instance Methods
     discovered during that time.
     
     *scan()* is equivalent to calling the *clear()*, *start()*, 
-    *process()* and *stop()* methods.
+    *process()* and *stop()* methods in order.
      
 .. function:: clear()
 
@@ -46,8 +46,46 @@ Instance Methods
     
 .. function:: start()
 
+    Enables reception of advertising broadcasts from peripherals.
+    Should be called before calling *process()*.
+
 .. function:: process ( [timeout = 10] )
 
+    Waits for advertising broadcasts and calls the *delegate* object
+    when they are received. Returns after the given *timeout* period
+    in seconds. This may be called multiple times (between calls to
+    *start()* and *stop()* ).
+    
 .. function:: stop()
 
+    Disables reception of advertising broadcasts. Should be called after
+    *process()* has returned.
+
+
+Sample code
+-----------
+
+Basic code to run a LE device scan follows this example::
+
+    from btle import Scanner, DefaultDelegate
+
+    class ScanDelegate(DefaultDelegate):
+        def __init__(self):
+            DefaultDelegate.__init__(self)
+
+        def handleDiscovery(self, dev, isNewDev, isNewData):
+            if isNewDev:
+                print "Discovered device", dev.addr
+            elif isNewData:
+                print "Received new data from", dev.addr
+    
+    devices = scanner.scan(10.0)
+
+    for dev in devices:
+        print "Device %s (%s), RSSI=%d dB" % (dev.addr, dev.atype, dev.rssi)
+        for (adtype, desc, value) in dev.getScanData():
+            print "  %s = %s" % (desc, value)
+
+See the documentation for ``ScanEntry`` for the information available via the *dev*
+parameter passed to the delegate.