From bbe1b58437eab5519f95498f59ecb7c931296644 Mon Sep 17 00:00:00 2001
From: Vladimir Pouzanov <farcaller@gmail.com>
Date: Thu, 5 Mar 2009 21:38:17 +0200
Subject: [PATCH] Added more api docs to CPObject

---
 Foundation/CPObject.j | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/Foundation/CPObject.j b/Foundation/CPObject.j
index eeb8406be1..90f59227dc 100644
--- a/Foundation/CPObject.j
+++ b/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
 {