1 files changed, 35 insertions, 0 deletions
diff --git a/doc/spa-design.dox b/doc/spa-design.dox
new file mode 100644
index 0000000..403e27d
--- /dev/null
+++ b/doc/spa-design.dox
@@ -0,0 +1,35 @@
+/** \page page_spa_design SPA Design
+
+# Conventions
+
+## Types
+
+Types are generally divided into two categories:
+
+- String types: They identify interfaces and highlevel object types.
+- Integer types: These are enumerations used in the parts where high
+                 performance/ease of use/low space overhead is needed.
+
+The SPA type is system is statis and very simple but still allows you
+to make and introspect complex object type hierarchies.
+
+See the type system docs for more info.
+
+## Error Codes
+
+SPA uses negative integers as errno style error codes. Functions that return an
+int result code generated an error when < 0. `spa_strerror()` can be used to
+get a string representation of the error code.
+
+SPA also has a way to encode asynchronous results. This is done by setting a
+high bit (bit 30, the `ASYNC_BIT`) in the result code and a sequence number
+in the lower bits. This result is normally identified as a positive success
+result code and the sequence number can later be matched to the completion
+event.
+
+## Useful Macros
+
+SPA comes with some useful macros defined in `<spa/utils/defs.h>` and a
+number of utility functions, see \ref spa_utils.
+
+*/