Added more api docs to CPObject

Foundation/CPObject.j

@@ -23,8 +23,41 @@
 /*!
     @class CPObject
     
-    CPObject is the root class for most Cappuccino classes. Your custom classes 
-    should almost always subclass CPObject or one of its children.
+    CPObject is the root class for most Cappuccino classes. Like in Objective-C,
+    you have to declare parent class explicitly in Objective-J, so your custom
+    classes should almost always subclass CPObject or one of its children.
+    
+    CPObject provides facilities for class allocation and initialization,
+    querying runtime about parent classes and available selectors, using KVC
+    (key-value coding).
+    
+    When you subclass CPObject, most of the time you override one selector - init.
+    It is called for default initialization of custom object. You must call
+    parent class init in your overriden code:
+    <pre>- (id)init
+{
+    self = [super init];
+    if(self) {
+        ... provide default initialization code for your object ...
+    }
+    return self;
+}</pre>
+    
+    One more useful thing to override is description(). This selector
+    is used to provide developer-readable information about object. description
+    selector is often used with CPLog debugging:
+    <pre>- (CPString)description
+{
+    return [CPString stringWithFormat:@"<SomeClass %d>", someValue];
+}</pre>
+    To get description value you can use %@ specifier everywhere where format
+    specifiers are allowed:
+    <pre>var inst = [[SomeClass alloc] initWithSomeValue:10];
+CPLog(@"Got some class: %@", inst);</pre>
+    would output:
+    <pre>Got some class: <SomeClass 10></pre>
+    
+    @todo document KVC usage.
 */
 @implementation CPObject
 {