From 7d4c2840eb32a5fc4a4e49cd273705ca87ba033e Mon Sep 17 00:00:00 2001 From: Ross Boucher Date: Sat, 30 May 2009 13:46:42 -0700 Subject: [PATCH] All Foundation classes briefed Conflicts: Foundation/CPSet.j Foundation/CPTimer.j Foundation/CPURLConnection.j --- Foundation/CPNotification.j | 15 ++++++++++----- Foundation/CPNotificationCenter.j | 16 +++++++++++----- Foundation/CPNull.j | 6 ++++-- Foundation/CPNumber.j | 4 +++- Foundation/CPObject.j | 3 ++- Foundation/CPRunLoop.j | 5 +++-- Foundation/CPSet.j | 19 ++++++++++++++++++- Foundation/CPSortDescriptor.j | 6 ++++-- Foundation/CPString.j | 8 +++++--- Foundation/CPTimer.j | 6 ++++-- Foundation/CPURLConnection.j | 1 + Foundation/CPURLRequest.j | 4 +++- Foundation/CPURLResponse.j | 3 +++ Foundation/CPUndoManager.j | 14 ++++++++++++-- Foundation/CPValue.j | 4 +++- 15 files changed, 86 insertions(+), 28 deletions(-) diff --git a/Foundation/CPNotification.j b/Foundation/CPNotification.j index f01e3a557..224401eb5 100644 --- a/Foundation/CPNotification.j +++ b/Foundation/CPNotification.j @@ -24,13 +24,18 @@ @import "CPException.j" -/*! - @ingroup foundation +/*! @class CPNotification - Represents a notification for posting to an CPNotificationCenter. Consists of a name, an object, and an optional dictionary. The notification center will check for observers registered to receive either notifications with the name, the object, or both and pass the notification instance on to them. + @ingroup foundation + @brief A notification that can be posted to a CPNotificationCenter. - To create a notification use one of the class methods. The default init method will throw a - CPUnsupportedMethodException. + Represents a notification for posting to an CPNotificationCenter. Consists + of a name, an object, and an optional dictionary. The notification center + will check for observers registered to receive either notifications with + the name, the object, or both and pass the notification instance on to them. + + To create a notification use one of the class methods. The default init + method will throw a CPUnsupportedMethodException. */ @implementation CPNotification : CPObject { diff --git a/Foundation/CPNotificationCenter.j b/Foundation/CPNotificationCenter.j index 7b60b1f82..76d793271 100644 --- a/Foundation/CPNotificationCenter.j +++ b/Foundation/CPNotificationCenter.j @@ -25,15 +25,21 @@ @import "CPNotification.j" @import "CPException.j" -/*! - @ingroup foundation -*/ var CPNotificationDefaultCenter = nil; -/*! @class CPNotificationCenter +/*! + @class CPNotificationCenter + @ingroup foundation + @brief Sends messages (CPNotification) between objects. - Cappuccino provides a framework for sending messages between objects within a process called notifications. Objects register with an CPNotificationCenter to be informed whenever other objects post CPNotifications to it matching certain criteria. The notification center processes notifications synchronously -- that is, control is only returned to the notification poster once every recipient of the notification has received it and processed it. + Cappuccino provides a framework for sending messages between objects within + a process called notifications. Objects register with an + CPNotificationCenter to be informed whenever other objects post + CPNotifications to it matching certain criteria. The notification center + processes notifications synchronously -- that is, control is only returned + to the notification poster once every recipient of the notification has + received it and processed it. */ @implementation CPNotificationCenter : CPObject { diff --git a/Foundation/CPNull.j b/Foundation/CPNull.j index 95a0122d4..a0aca8598 100644 --- a/Foundation/CPNull.j +++ b/Foundation/CPNull.j @@ -26,8 +26,10 @@ var CPNullSharedNull = nil; /*! - @ingroup foundation @class CPNull + @ingroup foundation + @brief An object representation of nil. + This class is used as an object representation of nil. This is handy when a collection only accepts objects as values, but you would like a nil representation in there. */ @@ -55,4 +57,4 @@ var CPNullSharedNull = nil; return CPNullSharedNull; } -@end \ No newline at end of file +@end diff --git a/Foundation/CPNumber.j b/Foundation/CPNumber.j index 4a7d70d6e..37a1c55b8 100644 --- a/Foundation/CPNumber.j +++ b/Foundation/CPNumber.j @@ -28,8 +28,10 @@ var __placeholder = new Number(), _CPNumberHashes = { }; /*! - @ingroup foundation @class CPNumber + @ingroup foundation + @brief A bridged object to native Javascript numbers. + This class primarily exists for source compatability. The JavaScript Number type can be changed on the fly based on context, so there is no need to call any of these methods. diff --git a/Foundation/CPObject.j b/Foundation/CPObject.j index a265dd95d..e22b327d8 100644 --- a/Foundation/CPObject.j +++ b/Foundation/CPObject.j @@ -21,8 +21,9 @@ */ /*! - @ingroup foundation @class CPObject + @ingroup foundation + @brief The root class from which most classes are subclassed. 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 diff --git a/Foundation/CPRunLoop.j b/Foundation/CPRunLoop.j index f79dba058..0884e4915 100644 --- a/Foundation/CPRunLoop.j +++ b/Foundation/CPRunLoop.j @@ -137,9 +137,10 @@ var _CPRunLoopPerformPool = [], var CPRunLoopLastNativeRunLoop = 0; -/*! - @ingroup foundation +/*! @class CPRunLoop + @ingroup foundation + @brief The main run loop for the application. CPRunLoop instances handle various utility tasks that must be performed repetitively in an application, such as processing input events. diff --git a/Foundation/CPSet.j b/Foundation/CPSet.j index ae7c3de05..824b925dc 100644 --- a/Foundation/CPSet.j +++ b/Foundation/CPSet.j @@ -5,7 +5,22 @@ * Created by Bailey Carlson * Extended by Ross Boucher * Extended by Nabil Elisa - * + * 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 + * * TODO: Needs to implement CPCoding, CPCopying. */ @@ -15,7 +30,9 @@ @import "CPEnumerator.j" /*! + @class CPSet @ingroup foundation + @brief An unordered collection of objects. */ @implementation CPSet : CPObject { diff --git a/Foundation/CPSortDescriptor.j b/Foundation/CPSortDescriptor.j index 6a03406cd..27dca8d9c 100755 --- a/Foundation/CPSortDescriptor.j +++ b/Foundation/CPSortDescriptor.j @@ -44,8 +44,10 @@ CPOrderedSame = 0; CPOrderedDescending = 1; /*! - @ingroup foundation @class CPSortDescriptor + @ingroup foundation + @brief Holds attributes necessary to describe how to sort a set of objects. + A CPSortDescriptor holds the attributes necessary to describe how to sort a set of objects. The sort descriptor instance holds a property key path to the sort item of the objects to compare, the method selector to call for sorting and the sort order. @@ -136,4 +138,4 @@ CPOrderedDescending = 1; return [[[self class] alloc] initWithKey:_key ascending:!_ascending selector:_selector]; } -@end \ No newline at end of file +@end diff --git a/Foundation/CPString.j b/Foundation/CPString.j index 5edd41eaa..30221450b 100644 --- a/Foundation/CPString.j +++ b/Foundation/CPString.j @@ -65,14 +65,16 @@ var CPStringRegexSpecialCharacters = [ CPStringRegexEscapeExpression = new RegExp("(\\" + CPStringRegexSpecialCharacters.join("|\\") + ")", 'g'); /*! - @ingroup foundation @class CPString + @ingroup foundation + @brief An immutable string (collection of characters). + CPString is an object that allows management of strings. Because CPString is based on the JavaScript String object, CPStrings are immutable, although the class does have methods that create new CPStrings generated from modifications to the - receiving instance.

+ receiving instance. -

A handy feature of CPString instances is that they can be used wherever a JavaScript is + A handy feature of CPString instances is that they can be used wherever a JavaScript is required, and vice versa. */ @implementation CPString : CPObject diff --git a/Foundation/CPTimer.j b/Foundation/CPTimer.j index b4ca08409..62d1dad7e 100644 --- a/Foundation/CPTimer.j +++ b/Foundation/CPTimer.j @@ -25,9 +25,11 @@ @import "CPDate.j" @import "CPRunLoop.j" -/*! +/*! + @class CPTimer @ingroup foundation - @brief A timer which can send a message after the given time interval. + + @brief A timer object that can send a message after the given time interval. */ @implementation CPTimer : CPObject { diff --git a/Foundation/CPURLConnection.j b/Foundation/CPURLConnection.j index 817e1b4bd..675a57cd5 100644 --- a/Foundation/CPURLConnection.j +++ b/Foundation/CPURLConnection.j @@ -37,6 +37,7 @@ var CPURLConnectionDelegate = nil; /*! @class CPURLConnection @ingroup foundation + @brief Provides loading of a URL request. An interface to downloading content at a specified URL. Using one of the class methods, you can obtain the data. diff --git a/Foundation/CPURLRequest.j b/Foundation/CPURLRequest.j index 7498a143a..290d4b26a 100644 --- a/Foundation/CPURLRequest.j +++ b/Foundation/CPURLRequest.j @@ -24,8 +24,10 @@ /*! - @ingroup foundation @class CPURLRequest + @ingroup foundation + @brief Contains data obtained during a request made with CPURLConnection. + A helper object for CPURLConnection, that contains data obtained during the life of a request. */ diff --git a/Foundation/CPURLResponse.j b/Foundation/CPURLResponse.j index 0e2159d93..ed524d940 100644 --- a/Foundation/CPURLResponse.j +++ b/Foundation/CPURLResponse.j @@ -30,7 +30,10 @@ CPString _textEncodingName; */ /*! + @class CPURLResponse @ingroup foundation + @brief Protocol agnostic information about a request to a specifc URL. + Contains protocol agnostic information about a request to a specific URL. */ @implementation CPURLResponse : CPObject diff --git a/Foundation/CPUndoManager.j b/Foundation/CPUndoManager.j index afba0dbae..0bab9cfc7 100644 --- a/Foundation/CPUndoManager.j +++ b/Foundation/CPUndoManager.j @@ -152,9 +152,19 @@ var _CPUndoGroupingParentKey = @"_CPUndoGroupingParentKey", @end /*! - @ingroup foundation @class CPUndoManager - CPUndoManager provides a general mechanism supporting implementation of user action "undo" in applications. Essentially, it allows you to store sequences of messages and receivers that need to be invoked to undo or redo an action. The various methods in this class provide for grouping of sets of actions, execution of undo or redo actions, and tuning behavior parameters such as the size of the undo stack. Each application entity with its own editing history (e.g., a document) should have its own undo manager instance. Obtain an instance through a simple [[CPUndoManager alloc] init] message. + @ingroup foundation + @brief A general mechanism for user action "undo". + + CPUndoManager provides a general mechanism supporting implementation of user + action "undo" in applications. Essentially, it allows you to store sequences + of messages and receivers that need to be invoked to undo or redo an action. + The various methods in this class provide for grouping of sets of actions, + execution of undo or redo actions, and tuning behavior parameters such as + the size of the undo stack. Each application entity with its own editing + history (e.g., a document) should have its own undo manager instance. + Obtain an instance through a simple [[CPUndoManager alloc] init] + message. */ @implementation CPUndoManager : CPObject { diff --git a/Foundation/CPValue.j b/Foundation/CPValue.j index a7d499f1d..e51f529a4 100644 --- a/Foundation/CPValue.j +++ b/Foundation/CPValue.j @@ -25,8 +25,10 @@ /*! - @ingroup foundation @class CPValue + @ingroup foundation + @brief A generic "value". Can be subclassed to hold specific data types. + The class can be subclassed to hold different types of scalar values. */ @implementation CPValue : CPObject