From f46aa870a7a7596fd7aa45edd9eff1fd6bf07c28 Mon Sep 17 00:00:00 2001
From: Ross Boucher <ross@280north.com>
Date: Sat, 30 May 2009 13:49:10 -0700
Subject: [PATCH] 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
---
 Foundation/CPArray.j            |  2 +-
 Foundation/CPAttributedString.j |  4 ++--
 Foundation/CPBundle.j           |  1 +
 Foundation/CPCoder.j            |  4 +++-
 Foundation/CPCountedSet.j       | 27 +++++++++++++++++++++++++--
 Foundation/CPData.j             |  6 +++++-
 Foundation/CPDate.j             |  8 ++++++--
 Foundation/CPDictionary.j       | 26 ++++++++++++++------------
 Foundation/CPEnumerator.j       | 10 +++++++---
 Foundation/CPException.j        |  4 +++-
 Foundation/CPIndexSet.j         |  5 ++---
 Foundation/CPInvocation.j       |  4 +++-
 Foundation/CPJSONPConnection.j  |  3 +--
 Foundation/CPKeyedArchiver.j    |  5 +++--
 Foundation/CPKeyedUnarchiver.j  |  2 ++
 15 files changed, 78 insertions(+), 33 deletions(-)

diff --git a/Foundation/CPArray.j b/Foundation/CPArray.j
index 5fc37cf41..6ee704681 100755
--- 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
index 299b4afcb..580ffde7d 100644
--- 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
index af82e2976..563655fc7 100644
--- 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
index a6f8105bc..e9a376fa0 100644
--- 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
index 26158ac9c..ccad1365f 100644
--- 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
index b77fbf4be..49be67df5 100644
--- 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
index f46dced2f..436c51a0c 100644
--- 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
index fff999a70..0233f439a 100755
--- 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>
+    @ingroup foundation
+    @brief A mutable key-value pair collection.
 
-     <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.
+    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
index 63e88d424..51d25b92a 100755
--- 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
\ No newline at end of file
+@end
diff --git a/Foundation/CPException.j b/Foundation/CPException.j
index f948902ab..69c34b579 100755
--- 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
index 198ad421a..50f7421a7 100644
--- 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
index 0ad03d9a9..9aca90a23 100644
--- 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
index d4a73a583..7076697f3 100644
--- 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
index 7b1eb0b9d..aebaf4adb 100644
--- 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
index 467737b2d..3a4f2a87b 100644
--- 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