@@ -33,10 +33,15 @@
  */
 + initialize;
 
 /**
  * Allocates memory for an instance of the class.
+ *
+ * alloc will never return nil, instead, it will throw an 
+ * OFAllocFailedException.
+ *
+ * \return The allocated object.
  */
 + alloc;
 
 /**
  * Allocated memory for an instance of the class and initializes the instance.
@@ -64,10 +69,14 @@
  withMethodFromClass: (Class)class;
 
 /**
  * Initialize the already allocated object.
  * Also sets up the memory pool for the object.
+ *
+ * Derived classes may override this, but need to do self = [super init] before
+ * they do any initialization themselves. init may never return nil, instead
+ * an exception (for example OFInitializationFailed) should be thrown.
  *
  * \return An initialized object
  */
 - init;