+/** @class Ref
+ * @brief A reference to an object which is identified by a universally-unique identifier (UUID).
+ *
+ * This class is a `pointer' to a thing. It will always know the
+ * UUID of the thing, and it may have a shared_ptr to the C++ object
+ * which represents the thing.
+ *
+ * If the Ref does not have a shared_ptr it may be given one by
+ * calling resolve() with a list of objects. The shared_ptr will be
+ * set up using any object on the list which has a matching ID.
+ */