gistfile1.diff

commit de7ef99e819e2f6091dee4ead0f400924e76ec08
Author: Vladimir Pouzanov <farcaller@gmail.com>
Date:   Sun Feb 8 19:23:25 2009 +0200

    Added more api docs to CPObject

diff --git a/Foundation/CPObject.j b/Foundation/CPObject.j
index a586e6a..b868521 100644
--- a/Foundation/CPObject.j
+++ b/Foundation/CPObject.j
@@ -23,13 +23,48 @@
 /*!
     @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
+/// @cond DOXYFIX
 {
     Class   isa;
 }
+/// @endcond
 
 + (void)load
 {