Improvements to documentation from review

Author: rwb27

docs/source/documentation.rst

@@ -5,11 +5,28 @@ Generated documentation
 
 LabThings describes its HTTP API in two ways: with a :ref:`wot_td` and with an OpenAPI_ document.
 
+.. _openapi:
+
+OpenAPI
+-------
+
 OpenAPI_ is a standard way to describe an HTTP interface. It lists all of the possible HTTP requests that may be made, along with a description of each one, and a description of the possible responses.
 
-Each :ref:`wot_thing` is documented by a Thing Description, which is a JSON document describing all of the ways to interact with that Thing. The WoT_ standard defines the `Thing Description`_ and includes a JSON Schema against which it may be validated.
+.. _gen_td:
+
+Thing Description
+-----------------
+
+Each :ref:`wot_thing` is documented by a Thing Description, which is a JSON document describing all of the ways to interact with that Thing (:ref:`wot_affordances`\ ). The WoT_ standard defines the `Thing Description`_ and includes a JSON Schema against which it may be validated.
+
+Thing Description documents are higher-level than OpenAPI_ and focus on the capabilities of the Thing. For example, they include a list of properties, where each action is described only once. LabThings treats the Thing Description as your public API, and as a general rule anything not described in the Thing Description is not available over HTTP or to a `.DirectThingClient`\ .
+
+Comparison of Thing Description and OpenAPI
+-------------------------------------------
+
+Thing Description aims to be a neat way to describe the capabilities of a Thing, while OpenAPI focuses on detailed documentation of every possible interaction with the server. Thing Description is a newer and less well adopted standard that's specific to the Web of Things, while OpenAPI has been around for a while and is widely used and understood as a general-purpose API description.
 
-Thing Description documents are higher-level than OpenAPI_ and focus on the capabilities of the Thing, rather than the HTTP endpoints. In general you would expect more HTTP endpoints than there are interaction affordances, so in principle client code based on a Thing Description should be more meaningful. However, OpenAPI is a much more widely adopted standard and so both forms of documentation are generated by LabThings-FastAPI.
+OpenAPI describes each HTTP endpoint individually. There are usually more HTTP endpoints than there are :ref:`wot_affordances` because a Property may have two endpoints, one to read its value and one to write it. Actions usually correspond to several endpoints; one to invoke the action, one to check the action's status, one to cancel it, and another to retrieve its output once it has finished. In principle, client code based on a Thing Description should be more meaningful because related endpoints can be grouped together into properties or actions that correspond to structures in the programming language (like methods and properties in Python). However, OpenAPI is a much more widely adopted standard and so both forms of documentation are generated by LabThings-FastAPI.
 
 .. _WoT: https://www.w3.org/WoT/
 .. _Thing Description: https://www.w3.org/TR/wot-thing-description/

docs/source/see_also.rst

@@ -8,14 +8,41 @@ LabThings-FastAPI makes quite heavy use of a few key concepts from external libr
 Descriptors
 -----------
 
-Descriptors are a way to itercept attribute access on an object. By default, attributes of an object are just variables - so an object called ``foo`` might have an attribute called ``bar``, and you may read its value with ``foo.bar``, write its value with ``foo.bar = "baz"``, and delete the attribute with ``del foo.bar``. If ``foo`` is a descriptor, Python will call the ``__get__`` method of that descriptor when it's read and the ``__set__`` method when it's written to. The descriptor protocol is described with plenty of examples in the `Descriptor Guide`_ in the Python documentation.
+Descriptors are a way to itercept attribute access on an object. By default, attributes of an object are just variables - so an object called ``foo`` might have an attribute called ``bar``, and you may read its value with ``foo.bar``, write its value with ``foo.bar = "baz"``, and delete the attribute with ``del foo.bar``. If ``foo`` is a descriptor, Python will call the ``__get__`` method of that descriptor when it's read and the ``__set__`` method when it's written to. You have quite probably used a descriptor already, because the built-in `~builtins.property` creates a descriptor object: that's what runs your getter method when the property is accessed. The descriptor protocol is described with plenty of examples in the `Descriptor Guide`_ in the Python documentation.
 
 In LabThings-FastAPI, descriptors are used to implement :ref:`wot_actions` and :ref:`wot_properties` on `.Thing` subclasses. The intention is that these will function like standard Python methods and properties, but will also be available over HTTP, along with automatic documentation in the :ref:`wot_td` and OpenAPI documents.
 
 There are a few useful notes that relate to many of the descriptors in LabThings-FastAPI:
 
-* Descriptor objects **may have more than one owner**. As a rule, a descriptor object (e.g. an instance of `.DataProperty`) is assigned to an attribute of one `.Thing` subclass. There may, however, be multiple *instances* of that class, so it is not safe to assume that the descriptor object corresponds to only one `.Thing`. This is why the `.Thing` is passed to the ``__get__`` method: we should ensure that any values being remembered are keyed to the owning `.Thing` and are not simply stored in the descriptor. Usually, this is done using `.WeakKeyDictionary` objects, which allow us to look up values based on the `.Thing`, without interfering with garbage collection.
+* Descriptor objects **may have more than one owner**. As a rule, a descriptor object
+    (e.g. an instance of `.DataProperty`) is assigned to an attribute of one `.Thing` subclass. There may, however, be multiple *instances* of that class, so it is not safe to assume that the descriptor object corresponds to only one `.Thing`. This is why the `.Thing` is passed to the ``__get__`` method: we should ensure that any values being remembered are keyed to the owning `.Thing` and are not simply stored in the descriptor. Usually, this is done using `.WeakKeyDictionary` objects, which allow us to look up values based on the `.Thing`, without interfering with garbage collection.
+
+    The example below shows how this can go wrong.
+
+    .. code-block:: python
+
+        class BadProperty:
+            "An example of a descriptor that has unwanted behaviour."
+            def __init__(self):
+                self._value = None
+            
+            def __get__(self, obj):
+                return self._value
+
+            def __set__(self, obj, val):
+                self._value = val
+
+        class BrokenExample:
+            myprop = BadProperty()
+
+        a = BrokenExample()
+        b = BrokenExample()
+
+        assert a.myprop is None
+        b.myprop = True
+        assert a.myprop is None  # FAILS because `myprop` shares values between a and b
+
 * Descriptor objects **may know their name**. Python calls ``__set_name__`` on a descriptor if it is available. This allows the descriptor to know the name of the attribute to which it is assigned. LabThings-FastAPI uses the name in the URL and in the Thing Description. When ``__set_name__`` is called, the descriptor **is also passed the class that owns it**. This allows us to check for type hints and docstrings that are part of the class, rather than part of the descriptor.
-* There is a convention that descriptors return their value when accessed as an instance attribute, but return themselves when accessed as a class attribute. We try to adhere to that convention.
+* There is a convention that descriptors return their value when accessed as an instance attribute, but return themselves when accessed as a class attribute (as done by `builtins.property`). LabThings adheres to that convention.
 
 .. _`Descriptor Guide`: https://docs.python.org/3/howto/descriptor.html

docs/source/tutorial/properties.rst

@@ -3,7 +3,16 @@
 Properties
 =========================
 
-:ref:`wot_properties` are values that can be read and written on a Thing. They are used to represent the state of the Thing, such as its current temperature, brightness, or status. Properties can be read using a ``GET`` request and written using a ``PUT`` or ``POST`` request. You can add properties to a `.Thing` by using `.property` (usually imported as ``lt.property``).
+
+
+Properties are values that can be read from and written to a Thing. They are used to represent the state of the Thing, such as its current temperature, brightness, or status. :ref:`wot_properties` are a key concept in the Web of Things standard.
+
+LabThings implements properties in a very similar way to the built-in Python `~builtins.property`. The key difference is that defining an attribute as a `.property` means that the property will be listed in the :ref:`gen_td` and exposed over HTTP. This is important for two reasons:
+
+* Only properties declared using `.property` (usually imported as ``lt.property``) can be accessed over HTTP. Regular attributes or properties using `builtins.property` are only available to your `.Thing` internally, except in some special cases.
+* Communication between `.Thing`\ s within a LabThings server should be done using a `.DirectThingClient` classs. The purpose of `.DirectThingClient` is to provide the same interface as a `.ThingClient` over HTTP, so it will also only expose functionality described in the Thing Description.
+
+You can add properties to a `.Thing` by using `.property` (usually imported as ``lt.property``).
 
 Data properties
 -------------------------
@@ -78,7 +87,9 @@ Functional properties may also have a "setter" method, which is called when the
             """Set the value of twice_my_property."""
             self.my_property = value // 2
 
-Adding a setter makes the property read-write (if only a getter is present, it must be read-only). It is possible to make a property read-only for clients by setting its ``readonly`` attribute: this has the same behaviour as for data properties, i.e. it prevents the property from being written to via HTTP requests or `.DirectThingClient` instances, but it can still be modified by the Thing's code.
+Adding a setter makes the property read-write (if only a getter is present, it must be read-only). 
+
+It is possible to make a property read-only for clients by setting its ``readonly`` attribute: this has the same behaviour as for data properties.
 
 .. code-block:: python
 
@@ -101,7 +112,21 @@ Adding a setter makes the property read-write (if only a getter is present, it m
         # Make the property read-only for clients
         twice_my_property.readonly = True
 
-Functional properties may not be observed, as they are not backed by a simple value. If you need to notify clients when the value changes, you can use a data property that is updated by the functional property.
+In the example above, ``twice_my_property`` may be set by code within ``MyThing`` but cannot be written to via HTTP requests or `.DirectThingClient` instances.
+
+Functional properties may not be observed, as they are not backed by a simple value. If you need to notify clients when the value changes, you can use a data property that is updated by the functional property. In the example above, ``my_property`` may be observed, while ``twice_my_property`` cannot be observed. It would be possible to observe changes in ``my_property`` and then query ``twice_my_property`` for its new value.
+
+HTTP interface
+--------------
+
+LabThings is primarily controlled using HTTP. Mozilla have a good `Overview of HTTP`_ that is worth a read if you are unfamiliar with the concept of requests, or what ``GET`` and ``PUT`` mean.
+
+Each property in LabThings will be assigned a URL, which allows it to be read and (optionally) written to. The easiest way to explore this is in the interactive OpenAPI documentation, served by your LabThings server at ``/docs``\ . Properties can be read using a ``GET`` request and written using a ``PUT`` request.
+
+LabThings follows the `HTTP Protocol Binding`_ from the Web of Things standard. That's quite a detailed document: for a gentle introduction to HTTP and what a request means, see 
+
+.. _`Overview of HTTP`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview
+.. _`HTTP Protocol Binding`: https://w3c.github.io/wot-binding-templates/bindings/protocols/http/index.html
 
 Observable properties
 -------------------------