Merge branch 'master' of gitorious@git.sugarlabs.org:question-support-api/mainline

1 files changed, 22 insertions, 0 deletions

diff --git a/doc/question_interface.rst b/doc/question_interface.rst
new file mode 100644
index 0000000..4b3e9c0
--- /dev/null
+++ b/doc/question_interface.rst
@@ -0,0 +1,22 @@
+Question
+========
+
+A Question object is guaranteed to have the following behavior:
+
+    - When initially created stores None as `response` and `submitted` is False.
+    - Whenever response is updated, the `correct` property is set to the credit
+      earned for the question (often actually set to True=1 and False=0, though
+      partial credit is possible).
+    - The `text` attribute of a question is the data object to be presented to
+      the user, along with possible answers, if any are given. The `text` and
+      `answers` fields will contain an object that can be passed to some subset
+      of the markup/media-type conversion functions to produce a value of the
+      appropriate type. (It is not recommended that you test types directly,
+      instead use the functions provided for this purpose).
+    - A `title` attribute will *always* be present on the object, though it may
+      be None.
+    - Some question types may have additional information required to present
+      them correctly.  It is recommended that generic functions, with
+      appropriate error handling, be used for rendering questions to the user.
+      (Generic functions are already used internally by the question API, so
+      the PEAK-Rules implementation is already available to users of the API).