adding briefs and unifying class header structure

Conflicts: Foundation/CPArray.j Foundation/CPAttributedString.j Foundation/CPBundle.j Foundation/CPCountedSet.j Foundation/CPIndexSet.j Foundation/CPJSONPConnection.j
280north · May 30, 2009 · f46aa87 · f46aa87
1 parent 7d4c284
commit f46aa87
Show file tree

Hide file tree

Showing 15 changed files with 79 additions and 34 deletions.
diff --git a/Foundation/CPArray.j b/Foundation/CPArray.j
@@ -87,9 +87,9 @@
 @end
 
 /*! 
-    @ingroup foundation
     @class CPArray
     @brief A mutable array backed by a JavaScript Array.
+    @ingroup foundation
 
     A mutable array class backed by a JavaScript Array.
     There is also a CPMutableArray class,

diff --git a/Foundation/CPAttributedString.j b/Foundation/CPAttributedString.j
@@ -25,7 +25,8 @@
 @import "CPDictionary.j"
 @import "CPRange.j"
 
-/*! @class CPAttributedString
+/*! 
+    @class CPAttributedString
     @ingroup foundation
     @brief A mutable character string with attributes.
 
@@ -805,7 +806,6 @@
     CPAttributedString already implements mutable methods and
     this class only exists for source compatability.
 */
-
 @implementation CPMutableAttributedString : CPAttributedString {}
 @end
 

diff --git a/Foundation/CPBundle.j b/Foundation/CPBundle.j
@@ -26,6 +26,7 @@
 @import "CPURLRequest.j"
 
 /*! 
+    @class CPBundle
     @ingroup foundation
     @brief Groups information about an application's code & resources.
 */

diff --git a/Foundation/CPCoder.j b/Foundation/CPCoder.j
@@ -25,8 +25,10 @@
 
 
 /*! 
-    @ingroup foundation
     @class CPCoder
+    @ingroup foundation
+    @brief Defines methods for use when archiving & restoring (enc/decoding).
+
     Top-level class defining methods for use when archiving (encoding) objects to a byte array 
     or file, and when restoring (decoding) objects. 
 */

diff --git a/Foundation/CPCountedSet.j b/Foundation/CPCountedSet.j
@@ -1,9 +1,32 @@
+/*
+ * CPCountedSet.j
+ * Foundation
+ *
+ * Created by .
+ * Copyright 2008, 280 North, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */
 
 @import "CPSet.j"
 
-/*!
+/*! 
+    @class CPCountedSet
     @ingroup foundation
-    @brief An mutable collection of objects and counts of their instances.
+    @brief An mutable collection which may contain a specific object
+    numerous times.
 */
 @implementation CPCountedSet : CPMutableSet
 {

diff --git a/Foundation/CPData.j b/Foundation/CPData.j
@@ -23,8 +23,12 @@
 @import "CPObject.j"
 @import "CPString.j"
 
-/*!
+/*! 
+    @class CPData
     @ingroup foundation
+    @brief A Cappuccino wrapper for any data type.
+
+
 */
 
 @implementation CPData : CPObject

diff --git a/Foundation/CPDate.j b/Foundation/CPDate.j
@@ -1,5 +1,5 @@
 /*
- * CPObject.j
+ * CPDate.j
  * Foundation
  *
  * Created by Thomas Robinson.
@@ -26,8 +26,12 @@
 
 var CPDateReferenceDate = new Date(Date.UTC(2001,1,1,0,0,0,0));
 
-/*!
+/*! 
+    @class CPDate
     @ingroup foundation
+    @brief A representation of a single point in time.
+
+
 */
 @implementation CPDate : CPObject
 { 

diff --git a/Foundation/CPDictionary.j b/Foundation/CPDictionary.j
@@ -57,20 +57,22 @@
 
 @end
 
-/*!  
-    @ingroup foundation
+/*! 
     @class CPDictionary
-     A dictionary is the standard way of passing around key-value pairs in
-     the Cappuccino framework. It is similar to the
-     <a href="http://java.sun.com/javase/6/docs/api/index.html">Java map interface</a>,
-     except all keys are CPStrings and values can be any
-     Cappuccino or JavaScript object.</p>
-
-     <p>If you are familiar with dictionaries in Cocoa, you'll notice that
-     there is no CPMutableDictionary class. The regular CPDictionary
-     has <code>setObject:</code> and <code>removeObjectForKey:</code> methods.
-     In Cappuccino there is no distinction between immutable and mutable classes.
-     They are all mutable.
+    @ingroup foundation
+    @brief A mutable key-value pair collection.
+
+    A dictionary is the standard way of passing around key-value pairs in
+    the Cappuccino framework. It is similar to the
+    <a href="http://java.sun.com/javase/6/docs/api/index.html">Java map interface</a>,
+    except all keys are CPStrings and values can be any
+    Cappuccino or JavaScript object.
+
+    If you are familiar with dictionaries in Cocoa, you'll notice that
+    there is no CPMutableDictionary class. The regular CPDictionary
+    has <code>setObject:</code> and <code>removeObjectForKey:</code> methods.
+    In Cappuccino there is no distinction between immutable and mutable classes.
+    They are all mutable.
 */
 @implementation CPDictionary : CPObject
 {

diff --git a/Foundation/CPEnumerator.j b/Foundation/CPEnumerator.j
@@ -23,10 +23,14 @@
 @import "CPObject.j"
 
 /*! 
-    @ingroup foundation
+    
 */
 
-/*! @class CPEnumerator
+/*! 
+    @class CPEnumerator
+    @ingroup foundation
+    @brief Defines an interface for enumerators.
+    
     CPEnumerator is a superclass (with useless method bodies)
     that defines an interface for subclasses to follow. The purpose of an
     enumerator is to be a convenient system for traversing over the elements
@@ -52,4 +56,4 @@
     return [];
 }
 
-@end
+@end
diff --git a/Foundation/CPException.j b/Foundation/CPException.j
@@ -31,8 +31,10 @@ CPRangeException                    = "CPRangeException";
 CPInternalInconsistencyException    = "CPInternalInconsistencyException";
 
 /*! 
-    @ingroup foundation
     @class CPException
+    @ingroup foundation
+    @brief Used to implement exception handling (creating & raising).
+
     An example of throwing an exception in Objective-J:
 <pre>
 // some code here...

diff --git a/Foundation/CPIndexSet.j b/Foundation/CPIndexSet.j
@@ -25,10 +25,9 @@
 
 
 /*! 
-    @ingroup foundation
     @class CPIndexSet
-
-    @brief A collection of unique integers (indexes).
+    @ingroup foundation
+    @brief A collection of unique integers.
 
     Instances of this class are collections of numbers. Each integer can appear
     in a collection only once.

diff --git a/Foundation/CPInvocation.j b/Foundation/CPInvocation.j
@@ -25,8 +25,10 @@
 
 
 /*! 
-    @ingroup foundation
     @class CPInvocation
+    @ingroup foundation
+    @brief An object representation of a message.
+
     A CPInvocation is an object representation of a message sent to an object.
 */
 @implementation CPInvocation : CPObject

diff --git a/Foundation/CPJSONPConnection.j b/Foundation/CPJSONPConnection.j
@@ -29,9 +29,8 @@ CPJSONPCallbackReplacementString = @"${JSONP_CALLBACK}";
 
 /*! 
     @ingroup foundation
-*/
+    @brief Allows cross domain connections using JSONP protocol.
 
-/*! @class CPJSONPConnection
     Important note: CPJSONPConnection is <strong>only</strong> for JSONP APIs.
     If aren't sure you <strong>need</strong>
     <a href="http://ajaxian.com/archives/jsonp-json-with-padding">JSON<strong>P</strong></a>,

diff --git a/Foundation/CPKeyedArchiver.j b/Foundation/CPKeyedArchiver.j
@@ -60,9 +60,10 @@ var _CPKeyedArchiverStringClass                         = Nil,
 }
 @end
 
-/*! 
-    @ingroup foundation
+/*!
     @class CPKeyedArchiver
+    @ingroup foundation
+    @brief Implements keyed archiving of object graphs (e.g. for storing data).
 
     Implements keyed archiving of object graphs. Archiving means to
     write data out in a format that be read in again later, or possibly

diff --git a/Foundation/CPKeyedUnarchiver.j b/Foundation/CPKeyedUnarchiver.j
@@ -51,7 +51,9 @@ var _CPKeyedUnarchiverArrayClass                                            = Ni
     _CPKeyedUnarchiverArchiverValueClass                                    = Nil;
 
 /*!
+    @class CPKeyedUnarchiver
     @ingroup foundation
+    @brief Unarchives objects created using CPKeyedArchiver.
 
     CPKeyedUnarchiver is used for creating objects out of
     coded files or CPData objects that were created by