From a05e116ceb277f96cd70d250ddc82d599827bd6a Mon Sep 17 00:00:00 2001
From: Nabil Elisa <nabil.elisa@gmail.com>
Date: Mon, 2 Feb 2009 02:35:30 +0000
Subject: [PATCH 1/8] see issue #114

---
 .../capp/Templates/ThemeDescriptor/index.html | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)
diff --git a/Tools/capp/Templates/ThemeDescriptor/index.html b/Tools/capp/Templates/ThemeDescriptor/index.html
index bea6f5f36..77a13e64d 100644
--- a/Tools/capp/Templates/ThemeDescriptor/index.html
+++ b/Tools/capp/Templates/ThemeDescriptor/index.html
@@ -28,7 +28,32 @@
     <body>
         <div style="position: absolute; left: 50%; top: 50%;">
             <center>
-                <img src = "Frameworks/AppKit/Resources/CPProgressIndicator/CPProgressIndicatorSpinningStyleRegular.gif" style="left: -32px; position: relative; top: -32px;" />
+                <script type = "text/javascript">
+                    document.write("<img src = \"Frameworks/AppKit/Resources/CPProgressIndicator/CPProgressIndicatorSpinningStyleRegular.gif\" style=\"left: -32px; position: relative; top: -32px;\" />");
+                </script>
+                
+                <noscript>
+                    <div style="width: 500px; height: 300px; background-color: #eeeeee; left: -250px; top: -150px; position: relative; text-align: left; -moz-border-radius: 20px; -webkit-border-radius: 20px; color: #555555">
+                        <p style="padding: 25px;">
+                            Javascript is required for this site to work correctly but is either disabled or not supported by your browser.
+                            <br/><br/><br/>
+                            
+                            You can fix this problem by doing one of the following:
+                            <ul style="margin-top: -30px">
+                                <li>Enable Javascript (<a href="http://www.google.com/search?q=enable+javascript">show me how</a>)</li>
+                                <li>Download a more recent version of a major browser
+                                    <ul>
+                                        <li><a href="http://www.google.com/chrome/">Chrome</a></li>
+                                        <li><a href="http://www.apple.com/safari/download/">Safari</a></li>
+                                        <li><a href="http://www.mozilla.com/en-US/firefox/">Firefox</a></li>
+                                        <li><a href="http://www.opera.com/download/">Opera</a></li>
+                                        <li><a href="http://www.microsoft.com/windows/downloads/ie/getitnow.mspx">Internet Explorer</a></li>
+                                    </ul>
+                                </li>
+                            </ul>
+                        </p>
+                    </div>
+                </noscript>
             </center>
         </div>
     </body>

From 9420c22298e1e1699a1166925baa1ac23186d057 Mon Sep 17 00:00:00 2001
From: Nabil Elisa <nabil.elisa@gmail.com>
Date: Tue, 3 Feb 2009 23:30:10 +0000
Subject: [PATCH 2/8] changed Javascript to JavaScript in all natural-language
 references.

---
 Tools/capp/Templates/ThemeDescriptor/index.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Tools/capp/Templates/ThemeDescriptor/index.html b/Tools/capp/Templates/ThemeDescriptor/index.html
index 77a13e64d..1980e27f9 100644
--- a/Tools/capp/Templates/ThemeDescriptor/index.html
+++ b/Tools/capp/Templates/ThemeDescriptor/index.html
@@ -35,13 +35,13 @@
                 <noscript>
                     <div style="width: 500px; height: 300px; background-color: #eeeeee; left: -250px; top: -150px; position: relative; text-align: left; -moz-border-radius: 20px; -webkit-border-radius: 20px; color: #555555">
                         <p style="padding: 25px;">
-                            Javascript is required for this site to work correctly but is either disabled or not supported by your browser.
+                            JavaScript is required for this site to work correctly but is either disabled or not supported by your browser.
                             <br/><br/><br/>
                             
                             You can fix this problem by doing one of the following:
                             <ul style="margin-top: -30px">
-                                <li>Enable Javascript (<a href="http://www.google.com/search?q=enable+javascript">show me how</a>)</li>
-                                <li>Download a more recent version of a major browser
+                                <li>Enable JavaScript (<a href="http://www.google.com/search?q=enable+javascript">show me how</a>)</li>
+                                <li>Download a recent version of a major browser
                                     <ul>
                                         <li><a href="http://www.google.com/chrome/">Chrome</a></li>
                                         <li><a href="http://www.apple.com/safari/download/">Safari</a></li>

From 65593c520044dec0f3db74cfa99eb484a547c018 Mon Sep 17 00:00:00 2001
From: Ross Boucher <ross@280north.com>
Date: Wed, 25 Mar 2009 00:57:10 -0700
Subject: [PATCH 3/8] Update styles for noscript section of index.html

---
 Tools/capp/Templates/Application/index.html   | 21 ++++++++++--
 .../capp/Templates/NibApplication/index.html  | 21 ++++++++++--
 .../capp/Templates/ThemeDescriptor/index.html | 32 +++++++------------
 3 files changed, 50 insertions(+), 24 deletions(-)

diff --git a/Tools/capp/Templates/Application/index.html b/Tools/capp/Templates/Application/index.html
index bea6f5f36..070cf81c5 100644
--- a/Tools/capp/Templates/Application/index.html
+++ b/Tools/capp/Templates/Application/index.html
@@ -6,7 +6,7 @@
 <!--
 //
 //  index.html
-//  __Product__
+//  noscript
 //
 //  Created by __Me__ on __Date__.
 //  Copyright 2008 __MyCompanyName__. All rights reserved.
@@ -28,7 +28,24 @@
     <body>
         <div style="position: absolute; left: 50%; top: 50%;">
             <center>
-                <img src = "Frameworks/AppKit/Resources/CPProgressIndicator/CPProgressIndicatorSpinningStyleRegular.gif" style="left: -32px; position: relative; top: -32px;" />
+                <script type = "text/javascript">
+                    document.write("<img src = \"Frameworks/AppKit/Resources/CPProgressIndicator/CPProgressIndicatorSpinningStyleRegular.gif\" style=\"left: -32px; position: relative; top: -32px;\" />");
+                </script>
+                
+                <noscript>
+                    <div style="width: 400px; padding: 10px 25px 20px 25px; font-family: sans-serif; background-color: #eeeeee; position: relative; left: -225px; top: -120px; text-align: center; -moz-border-radius: 20px; -webkit-border-radius: 20px; color: #555555">
+                        <p style="line-height: 1.4em;">JavaScript is required for this site to work correctly but is either disabled or not supported by your browser.</p>
+                        <p style="font-size:120%; padding:10px;"><a href="http://cappuccino.org/noscript">Show me how to enable JavaScript</a></p>
+                        <p style="font-size:80%;">You may want to upgrade to a newer browser while you're at it:</p>
+                        <ul style="margin:0;padding:0; text-align: center; font-size:80%;" >
+                            <li style="display: inline;"><a href="http://www.apple.com/safari/download/">Safari</a></li>
+                            <li style="display: inline;"><a href="http://www.mozilla.com/en-US/firefox/">Firefox</a></li>
+                            <li style="display: inline;"><a href="http://www.google.com/chrome/">Chrome</a></li>
+                            <li style="display: inline;"><a href="http://www.opera.com/download/">Opera</a></li>
+                            <li style="display: inline;"><a href="http://www.microsoft.com/windows/downloads/ie/getitnow.mspx">Internet Explorer</a></li>
+                        </ul>
+                    </div>
+                </noscript>
             </center>
         </div>
     </body>
diff --git a/Tools/capp/Templates/NibApplication/index.html b/Tools/capp/Templates/NibApplication/index.html
index bea6f5f36..070cf81c5 100644
--- a/Tools/capp/Templates/NibApplication/index.html
+++ b/Tools/capp/Templates/NibApplication/index.html
@@ -6,7 +6,7 @@
 <!--
 //
 //  index.html
-//  __Product__
+//  noscript
 //
 //  Created by __Me__ on __Date__.
 //  Copyright 2008 __MyCompanyName__. All rights reserved.
@@ -28,7 +28,24 @@
     <body>
         <div style="position: absolute; left: 50%; top: 50%;">
             <center>
-                <img src = "Frameworks/AppKit/Resources/CPProgressIndicator/CPProgressIndicatorSpinningStyleRegular.gif" style="left: -32px; position: relative; top: -32px;" />
+                <script type = "text/javascript">
+                    document.write("<img src = \"Frameworks/AppKit/Resources/CPProgressIndicator/CPProgressIndicatorSpinningStyleRegular.gif\" style=\"left: -32px; position: relative; top: -32px;\" />");
+                </script>
+                
+                <noscript>
+                    <div style="width: 400px; padding: 10px 25px 20px 25px; font-family: sans-serif; background-color: #eeeeee; position: relative; left: -225px; top: -120px; text-align: center; -moz-border-radius: 20px; -webkit-border-radius: 20px; color: #555555">
+                        <p style="line-height: 1.4em;">JavaScript is required for this site to work correctly but is either disabled or not supported by your browser.</p>
+                        <p style="font-size:120%; padding:10px;"><a href="http://cappuccino.org/noscript">Show me how to enable JavaScript</a></p>
+                        <p style="font-size:80%;">You may want to upgrade to a newer browser while you're at it:</p>
+                        <ul style="margin:0;padding:0; text-align: center; font-size:80%;" >
+                            <li style="display: inline;"><a href="http://www.apple.com/safari/download/">Safari</a></li>
+                            <li style="display: inline;"><a href="http://www.mozilla.com/en-US/firefox/">Firefox</a></li>
+                            <li style="display: inline;"><a href="http://www.google.com/chrome/">Chrome</a></li>
+                            <li style="display: inline;"><a href="http://www.opera.com/download/">Opera</a></li>
+                            <li style="display: inline;"><a href="http://www.microsoft.com/windows/downloads/ie/getitnow.mspx">Internet Explorer</a></li>
+                        </ul>
+                    </div>
+                </noscript>
             </center>
         </div>
     </body>
diff --git a/Tools/capp/Templates/ThemeDescriptor/index.html b/Tools/capp/Templates/ThemeDescriptor/index.html
index 1980e27f9..070cf81c5 100644
--- a/Tools/capp/Templates/ThemeDescriptor/index.html
+++ b/Tools/capp/Templates/ThemeDescriptor/index.html
@@ -6,7 +6,7 @@
 <!--
 //
 //  index.html
-//  __Product__
+//  noscript
 //
 //  Created by __Me__ on __Date__.
 //  Copyright 2008 __MyCompanyName__. All rights reserved.
@@ -33,25 +33,17 @@
                 </script>
                 
                 <noscript>
-                    <div style="width: 500px; height: 300px; background-color: #eeeeee; left: -250px; top: -150px; position: relative; text-align: left; -moz-border-radius: 20px; -webkit-border-radius: 20px; color: #555555">
-                        <p style="padding: 25px;">
-                            JavaScript is required for this site to work correctly but is either disabled or not supported by your browser.
-                            <br/><br/><br/>
-                            
-                            You can fix this problem by doing one of the following:
-                            <ul style="margin-top: -30px">
-                                <li>Enable JavaScript (<a href="http://www.google.com/search?q=enable+javascript">show me how</a>)</li>
-                                <li>Download a recent version of a major browser
-                                    <ul>
-                                        <li><a href="http://www.google.com/chrome/">Chrome</a></li>
-                                        <li><a href="http://www.apple.com/safari/download/">Safari</a></li>
-                                        <li><a href="http://www.mozilla.com/en-US/firefox/">Firefox</a></li>
-                                        <li><a href="http://www.opera.com/download/">Opera</a></li>
-                                        <li><a href="http://www.microsoft.com/windows/downloads/ie/getitnow.mspx">Internet Explorer</a></li>
-                                    </ul>
-                                </li>
-                            </ul>
-                        </p>
+                    <div style="width: 400px; padding: 10px 25px 20px 25px; font-family: sans-serif; background-color: #eeeeee; position: relative; left: -225px; top: -120px; text-align: center; -moz-border-radius: 20px; -webkit-border-radius: 20px; color: #555555">
+                        <p style="line-height: 1.4em;">JavaScript is required for this site to work correctly but is either disabled or not supported by your browser.</p>
+                        <p style="font-size:120%; padding:10px;"><a href="http://cappuccino.org/noscript">Show me how to enable JavaScript</a></p>
+                        <p style="font-size:80%;">You may want to upgrade to a newer browser while you're at it:</p>
+                        <ul style="margin:0;padding:0; text-align: center; font-size:80%;" >
+                            <li style="display: inline;"><a href="http://www.apple.com/safari/download/">Safari</a></li>
+                            <li style="display: inline;"><a href="http://www.mozilla.com/en-US/firefox/">Firefox</a></li>
+                            <li style="display: inline;"><a href="http://www.google.com/chrome/">Chrome</a></li>
+                            <li style="display: inline;"><a href="http://www.opera.com/download/">Opera</a></li>
+                            <li style="display: inline;"><a href="http://www.microsoft.com/windows/downloads/ie/getitnow.mspx">Internet Explorer</a></li>
+                        </ul>
                     </div>
                 </noscript>
             </center>

From 3fe872c125a7734e5629d5644d9fea8a0f813f10 Mon Sep 17 00:00:00 2001
From: Tom Robinson <tom@280north.com>
Date: Wed, 25 Mar 2009 00:56:01 -0700
Subject: [PATCH 4/8] Delete old blend and nib2cib directories

---
 AppKit/Tools/blend/blend | 57 ---------------------------------------
 Tools/nib2cib/nib2cib    | 58 ----------------------------------------
 2 files changed, 115 deletions(-)
 delete mode 100755 AppKit/Tools/blend/blend
 delete mode 100755 Tools/nib2cib/nib2cib

diff --git a/AppKit/Tools/blend/blend b/AppKit/Tools/blend/blend
deleted file mode 100755
index 7d3ae9cac..000000000
--- a/AppKit/Tools/blend/blend
+++ /dev/null
@@ -1,57 +0,0 @@
-#!/bin/sh
-# 
-# blend
-# blend
-# 
-# Created by Francisco Tolmasky.
-# 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
-# 
-
-# if OBJJ_HOME isn't set, try to determine it
-if [ -z $OBJJ_HOME ]; then
-    # get path of the executable
-    SELF_PATH=$(cd -P -- "$(dirname -- "$0")" && pwd -P) && SELF_PATH=$SELF_PATH/$(basename -- "$0")
-    
-    # resolve symlinks
-    if [ -h $SELF_PATH ]; then
-        SELF_PATH=`readlink $SELF_PATH`
-    fi
-    
-    # get second ancestor directory
-    SELF_DIR=`dirname $SELF_PATH`
-    export OBJJ_HOME=`dirname $SELF_DIR`
-    
-    # check to ensure it exists, print message
-    if [ -d $OBJJ_HOME ]; then
-        echo "OBJJ_HOME not set, defaulting to $OBJJ_HOME" 1>&2
-    else
-        echo "OBJJ_HOME not set, default at $OBJJ_HOME doesn't exist, exiting" 1>&2 
-        exit 2
-    fi
-fi
-
-OBJJ_LIB="$OBJJ_HOME/lib"
-
-BLEND="$OBJJ_LIB/blend/main.j"
-
-# convert paths for Cygwin
-if [[ `uname` == CYGWIN* ]]; then
-    OBJJ_HOME=`cygpath -w "$OBJJ_HOME"`
-    BAKE=`cygpath -w "$BLEND"`
-fi
-
-objj $BLEND $@
diff --git a/Tools/nib2cib/nib2cib b/Tools/nib2cib/nib2cib
deleted file mode 100755
index 338a66249..000000000
--- a/Tools/nib2cib/nib2cib
+++ /dev/null
@@ -1,58 +0,0 @@
-#!/bin/sh
-
-# 
-# nib2cib
-# nib2cib
-# 
-# Created by Francisco Tolmasky.
-# 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
-# 
-
-# if OBJJ_HOME isn't set, try to determine it
-if [ -z $OBJJ_HOME ]; then
-    # get path of the executable
-    SELF_PATH=$(cd -P -- "$(dirname -- "$0")" && pwd -P) && SELF_PATH=$SELF_PATH/$(basename -- "$0")
-    
-    # resolve symlinks
-    if [ -h $SELF_PATH ]; then
-        SELF_PATH=`readlink $SELF_PATH`
-    fi
-    
-    # get second ancestor directory
-    SELF_DIR=`dirname $SELF_PATH`
-    export OBJJ_HOME=`dirname $SELF_DIR`
-    
-    # check to ensure it exists, print message
-    if [ -d $OBJJ_HOME ]; then
-        echo "OBJJ_HOME not set, defaulting to $OBJJ_HOME" 1>&2
-    else
-        echo "OBJJ_HOME not set, default at $OBJJ_HOME doesn't exist, exiting" 1>&2 
-        exit 2
-    fi
-fi
-
-OBJJ_LIB="$OBJJ_HOME/lib"
-
-NIB2CIB="$OBJJ_LIB/nib2cib/main.j"
-
-# convert paths for Cygwin
-if [[ `uname` == CYGWIN* ]]; then
-    OBJJ_HOME=`cygpath -w "$OBJJ_HOME"`
-    BAKE=`cygpath -w "$NIB2CIB"`
-fi
-
-objj $NIB2CIB $@

From e5b0094f7da799fb37bf81329f91a985bc553f91 Mon Sep 17 00:00:00 2001
From: Tom Robinson <tom@280north.com>
Date: Wed, 25 Mar 2009 00:56:45 -0700
Subject: [PATCH 5/8] Remove unecessary header.txt reference

---
 Objective-J/Rakefile | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Objective-J/Rakefile b/Objective-J/Rakefile
index d9488ba85..e5644718c 100644
--- a/Objective-J/Rakefile
+++ b/Objective-J/Rakefile
@@ -17,8 +17,7 @@ $RHINO_FILE             = File.join($PRODUCT, 'rhino.platform', 'Objective-J.js'
 
 task :Products => [$BROWSER_FILE, $RHINO_FILE, $LICENSE_PRODUCT]
 
-Files = [   'header.txt',
-            'constants.js', 
+Files = [   'constants.js', 
             'utilities.js', 
             'runtime.js', 
             'dictionary.js', 

From e2eefe350d5b0f4aba91df4e143785e5747f188d Mon Sep 17 00:00:00 2001
From: Tom Robinson <tom@280north.com>
Date: Wed, 25 Mar 2009 00:57:23 -0700
Subject: [PATCH 6/8] require rubygems in case it isn't automatically

---
 common.rb | 1 +
 1 file changed, 1 insertion(+)

diff --git a/common.rb b/common.rb
index 30a80cef4..e66517d43 100644
--- a/common.rb
+++ b/common.rb
@@ -12,6 +12,7 @@ def gem_command
 end
 
 begin
+    require 'rubygems'
     require 'plist'
 rescue LoadError
     puts 'Plist gem not installed, installing...'

From 70da3e287d3667774db85caa7efd84d2dfaa2de5 Mon Sep 17 00:00:00 2001
From: Ross Boucher <ross@280north.com>
Date: Wed, 25 Mar 2009 01:35:47 -0700
Subject: [PATCH 7/8] Replace removed __Product__.

---
 Tools/capp/Templates/Application/index.html     | 2 +-
 Tools/capp/Templates/NibApplication/index.html  | 2 +-
 Tools/capp/Templates/ThemeDescriptor/index.html | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Tools/capp/Templates/Application/index.html b/Tools/capp/Templates/Application/index.html
index 070cf81c5..734929848 100644
--- a/Tools/capp/Templates/Application/index.html
+++ b/Tools/capp/Templates/Application/index.html
@@ -6,7 +6,7 @@
 <!--
 //
 //  index.html
-//  noscript
+//  __Product__
 //
 //  Created by __Me__ on __Date__.
 //  Copyright 2008 __MyCompanyName__. All rights reserved.
diff --git a/Tools/capp/Templates/NibApplication/index.html b/Tools/capp/Templates/NibApplication/index.html
index 070cf81c5..734929848 100644
--- a/Tools/capp/Templates/NibApplication/index.html
+++ b/Tools/capp/Templates/NibApplication/index.html
@@ -6,7 +6,7 @@
 <!--
 //
 //  index.html
-//  noscript
+//  __Product__
 //
 //  Created by __Me__ on __Date__.
 //  Copyright 2008 __MyCompanyName__. All rights reserved.
diff --git a/Tools/capp/Templates/ThemeDescriptor/index.html b/Tools/capp/Templates/ThemeDescriptor/index.html
index 070cf81c5..734929848 100644
--- a/Tools/capp/Templates/ThemeDescriptor/index.html
+++ b/Tools/capp/Templates/ThemeDescriptor/index.html
@@ -6,7 +6,7 @@
 <!--
 //
 //  index.html
-//  noscript
+//  __Product__
 //
 //  Created by __Me__ on __Date__.
 //  Copyright 2008 __MyCompanyName__. All rights reserved.

From f04a199f4ca288cbf04c49f5828fd95da18da362 Mon Sep 17 00:00:00 2001
From: stephen <stephen@stephen-desktop.(none)>
Date: Wed, 11 Mar 2009 20:55:06 +0000
Subject: [PATCH 8/8] Documentation for CPAttributedString

---
 Foundation/CPAttributedString.j | 238 +++++++++++++++++++++++++++++++-
 1 file changed, 236 insertions(+), 2 deletions(-)

diff --git a/Foundation/CPAttributedString.j b/Foundation/CPAttributedString.j
index 4f3fae50c..15a7c2768 100644
--- a/Foundation/CPAttributedString.j
+++ b/Foundation/CPAttributedString.j
@@ -23,6 +23,21 @@
 @import <Foundation/CPObject.j>
 @import <Foundation/CPString.j>
 
+/*! @class CPAttributedString
+    @ingroup foundation
+    @brief A mutable character string with attributes.
+
+    A character string with sets of attributes that apply to single or ranges of
+    characters. The attributes are containted within a CPDictionary class.
+    Attributes can be any name/value pair. The data type of the value is not
+    restricted.
+    This class is mutable.
+
+    @note Cocoa developers: in Cappuccino CPAttributedString is mutable. It
+    implements functionality from both NSAttributedString and
+    NSMutableAttributedString. However, to ease converting of existing
+    Objective-C code a CPMutableAttributedString alias to this class exists.
+*/
 @implementation CPAttributedString : CPObject
 {
     CPString    _string;
@@ -30,11 +45,21 @@
 }
 
 //Creating an NSAttributedString Object
+/*!
+    Creates a new attributed string from a character string.
+    @param aString is the string to initialise from.
+    @return a new CPAttributedString containing the string <code>aString</code>.
+*/
 - (id)initWithString:(CPString)aString
 {
     return [self initWithString:aString attributes:nil];
 }
- 
+
+/*!
+    Creates a new attributed string from an existing attributed string.
+    @param aString is the attributed string to initialise from.
+    @return a new CPAttributedString containing the string <code>aString</code>.
+*/ 
 - (id)initWithAttributedString:(CPAttributedString)aString
 {
     var string = [self initWithString:"" attributes:nil];
@@ -44,6 +69,14 @@
     return string;
 }
 
+/*!
+    Creates a new attributed string from a character string and the specified
+    dictionary of attributes.
+    @param aString is the attributed string to initialise from.
+    @param attributes is a dictionary of string attributes.
+    @return a new CPAttributedString containing the string <code>aString</code>
+    with associated attributes, <code>attributes</code>.
+*/ 
 - (id)initWithString:(CPString)aString attributes:(CPDictionary)attributes
 {
     self = [super init];
@@ -58,21 +91,37 @@
 }
 
 //Retrieving Character Information
+/*!
+    Returns a string containing the receiver's character data without
+    attributes.
+    @return a string of type CPString.
+*/ 
 - (CPString)string
 {
     return _string;
 }
 
+/*!
+    Returns a string containing the receiver's character data without
+    attributes.
+    @return a string of type CPString.
+*/ 
 - (CPString)mutableString
 {
     return [self string];
 }   
 
+/*!
+    Get the length of the string.
+    @return an unsigned integer equivalent to the number of characters in the
+    string.
+*/ 
 - (unsigned)length
 {
     return _string.length;
 }
 
+// private method
 - (unsigned)_indexOfEntryWithIndex:(unsigned)anIndex
 {
     if (anIndex < 0 || anIndex > _string.length || anIndex === undefined)
@@ -94,6 +143,24 @@
 }
 
 //Retrieving Attribute Information
+/*!
+    Returns a dictionary of attributes for the character at a given index. The
+    range in which this character resides in which the attributes are the
+    same, can be returned if desired. 
+    @note there is no guarantee that the range returned is in fact the complete
+    range of the particular attributes. To ensure this use
+    <code>attributesAtIndex:longestEffectiveRange:inRange:</code> instead. Note
+    however that it may take significantly longer to execute.
+    @param anIndex is an unsigned integer index. It must lie within the bounds
+    of the string.
+    @param aRange is a reference to a CPRange object
+    that is set (upon return) to the range over which the attributes are the
+    same as those at index, <code>anIndex</code>. If not required pass
+    <code>nil</code>.
+    @return a CPDictionary containing the attributes associated with the 
+    character at index <code>anIndex</code>. Returns <code>nil</code> if index
+    is out of bounds.
+*/ 
 - (CPDictionary)attributesAtIndex:(unsigned)anIndex effectiveRange:(CPRangePointer)aRange
 {
     //find the range entry that contains anIndex.
@@ -112,6 +179,27 @@
     return matchingRange.attributes;
 }
 
+/*!
+    Returns a dictionary of all attributes for the character at a given index
+    and, by reference, the range over which the attributes apply. This is the
+    maximum range both forwards and backwards in the string over which the
+    attributes apply, bounded in both directions by the range limit parameter,
+    <code>rangeLimit</code>.
+    @note this method performs a search to find this range which may be
+    computationally intensive. Use the <code>rangeLimit</code> to limit the
+    search space or use <code>attributesAtIndex:effectiveRange:</code> but
+    note that it is not guaranteed to return the full range of the current
+    character's attributes.
+    @param anIndex is the unsigned integer index. It must lie within the bounds
+    of the string.
+    @param aRange is a reference to a CPRange object that is set (upon return)
+    to the range over which the attributes apply.
+    @param rangeLimit a range limiting the search for the attributes' applicable
+    range.
+    @return a CPDictionary containing the attributes associated with the 
+    character at index <code>anIndex</code>. Returns <code>nil</code> if index
+    is out of bounds.
+*/ 
 - (CPDictionary)attributesAtIndex:(unsigned)anIndex longestEffectiveRange:(CPRangePointer)aRange inRange:(CPRange)rangeLimit
 {    
     var startingEntryIndex = [self _indexOfEntryWithIndex:anIndex];
@@ -172,6 +260,22 @@
     return comparisonDict;
 }
 
+/*!
+    Returns the specified named attribute for the given character index and, if
+    required, the range over which the attribute applies. 
+    @note there is no guarantee that the range returned is in fact the complete
+    range of a particular attribute. To ensure this use
+    <code>attribute:atIndex:longestEffectiveRange:inRange:</code> instead but
+    note that it may take significantly longer to execute.
+    @param attribute the name of the desired attribute.
+    @param anIndex is an unsigned integer character index from which to retrieve
+    the attribute. It must lie within the bounds of the string.
+    @param aRange is a reference to a CPRange object, that is set upon return
+    to the range over which the named attribute applies.  If not required pass
+    <code>nil</code>.
+    @return the named attribute or <code>nil</code> is the attribute does not
+    exist.
+*/ 
 - (id)attribute:(CPString)attribute atIndex:(unsigned)index effectiveRange:(CPRangePointer)aRange
 {
     if (!attribute)
@@ -188,6 +292,27 @@
     return [[self attributesAtIndex:index effectiveRange:aRange] valueForKey:attribute];
 }
 
+/*!
+    Returns the specified named attribute for the given character index and the
+    range over which the attribute applies. This is the maximum range both
+    forwards and backwards in the string over which the attribute applies,
+    bounded in both directions by the range limit parameter,
+    <code>rangeLimit</code>.
+    @note this method performs a search to find this range which may be
+    computationally intensive. Use the <code>rangeLimit</code> to limit the
+    search space or use <code>attribute:atIndex:effectiveRange:</code> but
+    note that it is not guaranteed to return the full range of the current
+    character's named attribute.
+    @param attribute the name of the desired attribute.
+    @param anIndex is an unsigned integer character index from which to retrieve
+    the attribute. It must lie within the bounds of the string.
+    @param aRange  is a reference to a CPRange object, that is set upon return
+    to the range over which the named attribute applies.
+    @param rangeLimit a range limiting the search for the attribute's applicable
+    range.
+    @return the named attribute or <code>nil</code> is the attribute does not
+    exist.
+*/
 - (id)attribute:(CPString)attribute atIndex:(unsigned)anIndex longestEffectiveRange:(CPRangePointer)aRange inRange:(CPRange)rangeLimit
 {
     //find the range entry that contains anIndex.
@@ -250,6 +375,12 @@
 }
 
 //Comparing Attributed Strings
+/*!
+    Compares the receiver's characters and attributes to the specified
+    attributed string, <code>aString</code>, and tests for equality.
+    @param aString the CPAttributedString to compare.
+    @return a boolean indicating equality.
+*/
 - (BOOL)isEqualToAttributedString:(CPAttributedString)aString
 {
 	if(!aString)
@@ -277,6 +408,13 @@
     return YES;
 }
 
+/*!
+    Determine whether the given object is the same as the receiver. If the
+    specified object is an attributed string then an attributed string compare
+    is performed.
+    @param anObject an object to test for equality.
+    @return a boolean indicating equality.
+*/
 - (BOOL)isEqual:(id)anObject
 {
 	if (anObject == self)
@@ -289,6 +427,13 @@
 }
 
 //Extracting a Substring
+/*!
+    Extracts a substring from the receiver, both characters and attributes,
+    within the range given by <code>aRange</code>.
+    @param aRange the range of the substring to extract.
+    @return a CPAttributedString containing the desired substring.
+    @exception CPRangeException if the range lies outside the receiver's bounds.
+*/
 - (CPAttributedString)attributedSubstringFromRange:(CPRange)aRange
 {
     if (!aRange || CPMaxRange(aRange) > _string.length || aRange.location < 0)
@@ -337,6 +482,17 @@
 }
 
 //Changing Characters
+/*! 
+    Replaces the characters in the receiver with those of the specified string
+    over the range, <code>aRange</code>. The new characters inherit the
+    attributes of the first character in the range that they replace.
+    @note the replacement string need not be the same length as the range
+    being replaced. The full <code>aString</code> is inserted and thus the
+    receiver's length changes to match this
+    @param aRange the range of characters to replace.
+    @param aString the string to replace the specified characters in the
+    receiver.
+*/
 - (void)replaceCharactersInRange:(CPRange)aRange withString:(CPString)aString
 {
     [self beginEditing];
@@ -372,12 +528,27 @@
     [self endEditing];
 }
 
+/*!
+    Deletes a range of characters and their associated attributes.
+    @param aRange a CPRange indicating the range of characters to delete.
+*/
 - (void)deleteCharactersInRange:(CPRange)aRange
 {
     [self replaceCharactersInRange:aRange withString:nil];
 }
 
 //Changing Attributes
+/*!
+    Sets the attributes of the specified character range. 
+
+    @note This process removes the attributes already associated with the 
+    character range. If you wish to retain the current attributes use
+    <code>addAttributes:range:</code>.
+    @param aDictionary a CPDictionary of attributes (names and values) to set
+    to.
+    @param aRange a CPRange indicating the range of characters to set their
+    associated attributes to <code>aDictionary</code>.
+*/
 - (void)setAttributes:(CPDictionary)aDictionary range:(CPRange)aRange
 {
     [self beginEditing];
@@ -398,6 +569,16 @@
     [self endEditing];
 }
 
+/*!
+    Add a collection of attributes to the specified character range. 
+
+    @note Attributes currently associated with the characters in the range are
+    untouched. To remove all previous attributes when adding use
+    <code>setAttributes:range:</code>.  
+    @param aDictionary a CPDictionary of attributes (names and values) to add.
+    @param aRange a CPRange indicating the range of characters to add the
+    attributes to.
+*/
 - (void)addAttributes:(CPDictionary)aDictionary range:(CPRange)aRange
 {
     [self beginEditing];
@@ -426,22 +607,54 @@
     [self endEditing];
 }
 
+/*!
+    Add an attribute with the given name and value to the specified character
+    range.
+
+    @note Attributes currently associated with the characters in the range are
+    untouched. To remove all previous attributes when adding use
+    <code>setAttributes:range:</code>.
+    @param anAttribute a CPString of the attribute name.
+    @param aValue a value to assign to the attribute. Can be of any type.
+    @param aRange a CPRange indicating the range of characters to add the
+    attribute too.
+*/
 - (void)addAttribute:(CPString)anAttribute value:(id)aValue range:(CPRange)aRange
 {
     [self addAttributes:[CPDictionary dictionaryWithObject:aValue forKey:anAttribute] range:aRange];
 }
 
+/*!
+    Remove a named attribute from a character range.
+    @param anAttribute a CPString specifying the name of the attribute.
+    @param aRange a CPRange indicating the range of character from which the
+    attribute will be removed.
+*/
 - (void)removeAttribute:(CPString)anAttribute range:(CPRange)aRange
 {
     [self addAttribute:anAttribute value:nil range:aRange];
 }
 
 //Changing Characters and Attributes
+/*!
+    Append an attributed string (characters and attributes) on to the end of
+    the receiver.
+    @param aString a CPAttributedString to append.
+*/
 - (void)appendAttributedString:(CPAttributedString)aString
 {
     [self insertAttributedString:aString atIndex:_string.length];
 }
 
+/*!
+    Inserts an attributed string (characters and attributes) at index,
+    <code>anIndex</code>, into the receiver. The portion of the
+    receiver's attributed string from the specified index to the end is shifted
+    until after the inserted string.
+    @param aString a CPAttributedString to insert.
+    @param anIndex the index at which the insert is to occur.
+    @exception CPRangeException If the index is out of bounds.
+*/
 - (void)insertAttributedString:(CPAttributedString)aString atIndex:(CPString)anIndex
 {
     [self beginEditing];
@@ -479,6 +692,14 @@
     [self endEditing];
 }
 
+/*!
+    Replaces characters and attributes in the range <code>aRange</code> with
+    those of the given attributed string, <code>aString</code>.
+    @param aRange a CPRange object specifying the range of characters and
+    attributes in the object to replace.
+    @param aString a CPAttributedString containing the data to be used for
+    replacement.
+*/
 - (void)replaceCharactersInRange:(CPRange)aRange withAttributedString:(CPAttributedString)aString
 {
     [self beginEditing];
@@ -489,6 +710,11 @@
     [self endEditing];
 }
 
+/*!
+    Sets the objects characters and attributes to those of <code>aString</code>.
+    @param aString is a CPAttributedString from which the contents will be
+    copied.
+*/
 - (void)setAttributedString:(CPAttributedString)aString
 {
     [self beginEditing];
@@ -546,11 +772,19 @@
 }
 
 //Grouping Changes
+/*!
+    This function is deliberately empty. It is provided to ease code converting
+    from Cocoa.
+*/
 - (void)beginEditing
 {
     //do nothing (says cocotron and gnustep)
 }
 
+/*!
+    This function is deliberately empty. It is provided to ease code converting
+    from Cocoa.
+*/
 - (void)endEditing
 {
     //do nothing (says cocotron and gnustep)
@@ -593,4 +827,4 @@ var splitRangeEntry = function splitRangeEntryAtIndex(/*RangeEntry*/aRangeEntry,
     newRangeEntry.attributes = [newRangeEntry.attributes copy];
     
     return [aRangeEntry, newRangeEntry];
-}
\ No newline at end of file
+}
