Changeset 71:354bda0cd5ac in xplra for doc/overview.dox

Timestamp:

04/13/13 13:05:40 (11 years ago)

Author:

István Váradi <ivaradi@…>

Branch:

default

hg-Phase:

(<MercurialRepository 3 'hg:/home/ivaradi/xplane/hg/xplra' '/'>, 'public')

Message:

Added the Python documentation

File:

• doc/overview.dox (modified) (1 diff)

doc/overview.dox

@@ -770 +770 @@
 /*! \page pythonapi Python Client API
  *
+ * The Python client API is implemented as a single module. Its
+ * central class is \ref xplra.XPlane. To communicate with the plugin
+ * in X-Plane, create an instance of it and call its \ref
+ * xplra.XPlane.connect "connect" function. This tries to establish
+ * the connection, and throws the standard I/O exceptions if it fails.
+ *
+ * The class can be used to perform the various operations provided by
+ * the plugin. In case of a failure and exception is thrown. If the
+ * plugin signals an error, a \ref xplra.ProtocolException
+ * "ProtocolException" is thrown with the error information provided
+ * by the plugin. In other cases some standard exception is thrown,
+ * which is mostly IOError if a communication error occurs.
+ *
+ * The \c XPlane object can be reused in the sense, that after you
+ * have made a connection, you can disconnect and then connect
+ * again. This may be useful, if X-Plane crashes for some reason, and
+ * you can then reconnect if the user has restarted it.
+ *
+ * Objects to store information about multi-dataref queries can be
+ * created by the \ref xplra.XPlane.createMultiGetter
+ * "createMultiGetter" function. It returns an instance of \ref
+ * xplra.MultiGetter, which can be used to store a number of datarefs
+ * and then execute a multi-dataref query for those datarefs. Before
+ * execution, the query can be \ref xplra.MultiBuffer.register
+ * "registered" in the plugin, so that the client does not have to send
+ * all the dataref information whenever the query is executed.
+ *
+ * The \c XPlane object knows about any multi-dataref query objects.
+ * Therefore if you register such a multi-dataref query, and then the
+ * connection breaks, and then you reconnect, the query will-be
+ * re-registered too, i.e. you don't have to do it yourself.
+ *
+ * Similarly, the \ref xplra.XPlane.createMultiSetter
+ * "createMultiSetter" function can be used to create a multi-dataref
+ * update object. They are handled the same way by \c XPlane as the
+ * query objects when it comes to registration and re-registration.
+ *
+ * The other functions of \c XPlane are mostly self-explanatory: they
+ * perform the operations defined by the protocol.
  */