Merging conflict

Merge branch 'master' into merge_branch

Conflicts:
	AppKit/Cib/CPCustomView.j

AppKit/CoreGraphics/CGAffineTransform.j

@@ -45,12 +45,24 @@ _function(CGAffineTransformEqualToTransform(lhs, rhs))
 
 _function(CGStringCreateWithCGAffineTransform(aTransform))
 
-// FIXME: !!!!
+/*
+    FIXME: !!!!
+    @return void
+    @group CGAffineTransform
+*/
 function CGAffineTransformCreateCopy(aTransform)
 {
     return _CGAffineTransformMakeCopy(aTransform);
 }
 
+/*
+    Returns a transform that rotates a coordinate system.
+    @param anAngle the amount in radians for the transform
+    to rotate a coordinate system
+    @return CGAffineTransform the transform with a specified
+    rotation
+    @group CGAffineTransform
+*/
 function CGAffineTransformMakeRotation(anAngle)
 {
     var sin = SIN(anAngle),
@@ -59,6 +71,13 @@ function CGAffineTransformMakeRotation(anAngle)
     return _CGAffineTransformMake(cos, sin, -sin, cos, 0.0, 0.0);
 }
 
+/*
+    Rotates a transform.
+    @param aTransform the transform to rotate
+    @param anAngle the amount to rotate in radians
+    @return void
+    @group CGAffineTransform
+*/
 function CGAffineTransformRotate(aTransform, anAngle)
 {
     var sin = SIN(anAngle),
@@ -74,6 +93,12 @@ function CGAffineTransformRotate(aTransform, anAngle)
         };
 }
 
+/*
+    Inverts a transform.
+    @param aTransform the transform to invert
+    @return CGAffineTransform an inverted transform
+    @group CGAffineTransform
+*/
 function CGAffineTransformInvert(aTransform)
 {
     var determinant = 1 / (aTransform.a * aTransform.d - aTransform.b * aTransform.c);
@@ -88,6 +113,14 @@ function CGAffineTransformInvert(aTransform)
     };
 }
 
+/*
+    Applies a transform to the rectangle's points. The transformed rectangle
+    will be the smallest box that contains the transformed points.
+    @param aRect the rectangle to transform
+    @param anAffineTransform the transform to apply
+    @return CGRect the new transformed rectangle
+    @group CGAffineTransform
+*/
 function CGRectApplyAffineTransform(aRect, anAffineTransform)
 {
     var top = _CGRectGetMinY(aRect),
@@ -106,6 +139,12 @@ function CGRectApplyAffineTransform(aRect, anAffineTransform)
     return _CGRectMake(minX, minY, (maxX - minX), (maxY - minY));
 }
 
+/*
+    Creates and returns a string representation of an affine transform.
+    @param anAffineTransform the transform to represent as a string
+    @return CPString a string describing the transform
+    @group CGAffineTransform
+*/
 function CPStringFromCGAffineTransform(anAffineTransform)
 {
     return '{' + anAffineTransform.a + ", " + anAffineTransform.b + ", " + anAffineTransform.c + ", " + anAffineTransform.d + ", " + anAffineTransform.tx + ", " + anAffineTransform.ty + '}';

AppKit/CoreGraphics/CGColor.j

@@ -45,15 +45,28 @@ function CGColorGetConstantColor(aColorName)
     alert("FIX ME");
 }
 
+/*
+    This function is for source compatability.    
+*/
 function CGColorRetain(aColor)
 {
     return aColor;
 }
 
+/*
+    This function is for source compatability.    
+*/
 function CGColorRelease()
 {
 }
 
+/*
+    Creates a new <objj>CGColor</objj>.
+    @param aColorSpace the <objj>CGColorSpace</objj> of the color
+    @param components the color's intensity values plus alpha
+    @return CGColor the new color object
+    @group CGColor
+*/
 function CGColorCreate(aColorSpace, components)
 {
     if (!aColorSpace || !components)
@@ -71,27 +84,68 @@ function CGColorCreate(aColorSpace, components)
     return _CGColorMap[UID] = { colorspace:aColorSpace, pattern:NULL, components:components };
 }
 
+/*
+    Creates a copy of a color... but not really. <objj>CGColor</objj>s
+    are immutable, so to be efficient, this function will just
+    return the same object that was passed in.
+    @param aColor the <objj>CGColor</objj> to 'copy'
+    @return CGColor the color copy
+    @group CGColor
+*/
 function CGColorCreateCopy(aColor)
 {
     // Colors should be treated as immutable, so don't mutate it!
     return aColor;
 }
 
+/*
+    Creates a gray color object.
+    @param gray the value to use for the color intensities (<code>0.0-1.0</code>)
+    @param alpha the gray's alpha value (<code>0.0-1.0</code>)
+    @return CGColor the new gray color object
+    @group CGColor
+*/
 function CGColorCreateGenericGray(gray, alpha)
 {
     return CGColorCreate(0, [gray, alpha]);
 }
 
+/*
+    Creates an RGB color.
+    @param red the red component (<code>0.0-1.0</code>)
+    @param green the green component (<code>0.0-1.0</code>)
+    @param blue the blue component (<code>0.0-1.0</code>)
+    @param alpha the alpha component (<code>0.0-1.0</code>)
+    @return CGColor the RGB based color
+    @group CGColor
+*/
 function CGColorCreateGenericRGB(red, green, blue, alpha)
 {
     return CGColorCreate(0, [red, green, blue, alpha]);
 }
 
+/*
+    Creates a CMYK color.
+    @param cyan the cyan component (<code>0.0-1.0</code>)
+    @param magenta the magenta component (<code>0.0-1.0</code>)
+    @param yellow the yellow component (<code>0.0-1.0</code>)
+    @param black the black component (<code>0.0-1.0</code>)
+    @param alpha the alpha component (<code>0.0-1.0</code>)
+    @return CGColor the CMYK based color
+    @group CGColor
+*/
 function CGColorCreateGenericCMYK(cyan, magenta, yellow, black, alpha)
 {
     return CGColorCreate(0, [cyan, magenta, yellow, black, alpha]);
 }
 
+/*
+    Creates a copy of the color with a specified alpha.
+    @param aColor the color object to copy
+    @param anAlpha the new alpha component for the copy (<code>0.0-1.0</code>)
+    @return CGColor the new copy
+    @group CGColor
+*/
 function CGColorCreateCopyWithAlpha(aColor, anAlpha)
 {
     var components = aColor.components;
@@ -109,6 +163,14 @@ function CGColorCreateCopyWithAlpha(aColor, anAlpha)
     return copy;
 }
 
+/*
+    Creates a color using the specified pattern.
+    @param aColorSpace the <objj>CGColorSpace</objj>
+    @param aPattern the pattern image
+    @param components the color components plus the alpha component
+    @return CGColor the patterned color
+    @group CGColor
+*/
 function CGColorCreateWithPattern(aColorSpace, aPattern, components)
 {
     if (!aColorSpace || !aPattern || !components)
@@ -117,6 +179,13 @@ function CGColorCreateWithPattern(aColorSpace, aPattern, components)
     return { colorspace:aColorSpace, pattern:aPattern, components:components.slice() };
 }
 
+/*
+    Determines if two colors are the same.
+    @param lhs the first <objj>CGColor</objj>
+    @param rhs the second <objj>CGColor</objj>
+    @return <code>YES</code> if the two colors are equal.
+    <code>NO</code> otherwise.
+*/
 function CGColorEqualToColor(lhs, rhs)
 {
     if (lhs == rhs)
@@ -145,6 +214,12 @@ function CGColorEqualToColor(lhs, rhs)
     return true;
 }
 
+/*
+    Returns the color's alpha component.
+    @param aColor the color
+    @return float the alpha component (<code>0.0-1.0</code>)
+    @group CGColor
+*/
 function CGColorGetAlpha(aColor)
 {
     var components = aColor.components;
@@ -152,21 +227,45 @@ function CGColorGetAlpha(aColor)
     return components[components.length - 1];
 }
 
+/*
+    Returns the <objj>CGColor</objj>'s color space.
+    @return <objj>CGColorSpace</objj>
+    @group CGColor
+*/
 function CGColorGetColorSpace(aColor)
 {
     return aColor.colorspace;
 }
 
+/*
+    Returns the <objj>CGColor</objj>'s components
+    including the alpha in an array.
+    @param aColor the color
+    @return CPArray the color's components
+*/
 function CGColorGetComponents(aColor)
 {
     return aColor.components;
 }
 
+/*
+    Returns the number of color components
+    (including alpha) in the specified color.
+    @param aColor the <objj>CGColor</objj>
+    @return CPNumber the number of components
+    @group CGColor
+*/
 function CGColorGetNumberOfComponents(aColor)
 {
     return aColor.components.length;
 }
 
+/*
+    Gets the <objj>CGColor</objj>'s pattern.
+    @param a <objj>CGColor</objj>
+    @return CGPatternFIXME the pattern image
+    @group CGColor
+*/
 function CGColorGetPattern(aColor)
 {
     return aColor.pattern;

AppKit/CoreGraphics/CGColorSpace.j

@@ -29,12 +29,40 @@ kCGColorSpaceModelDeviceN       = 4;
 kCGColorSpaceModelIndexed       = 5;
 kCGColorSpaceModelPattern       = 6;
 
+/*
+    @global
+    @group CGColorSpace
+*/
 kCGColorSpaceGenericGray        = "CGColorSpaceGenericGray";
+/*
+    @global
+    @group CGColorSpace
+*/
 kCGColorSpaceGenericRGB         = "CGColorSpaceGenericRGB";
+/*
+    @global
+    @group CGColorSpace
+*/
 kCGColorSpaceGenericCMYK        = "CGColorSpaceGenericCMYK";
+/*
+    @global
+    @group CGColorSpace
+*/
 kCGColorSpaceGenericRGBLinear   = "CGColorSpaceGenericRGBLinear";
+/*
+    @global
+    @group CGColorSpace
+*/
 kCGColorSpaceGenericRGBHDR      = "CGColorSpaceGenericRGBHDR";
+/*
+    @global
+    @group CGColorSpace
+*/
 kCGColorSpaceAdobeRGB1998       = "CGColorSpaceAdobeRGB1998";
+/*
+    @global
+    @group CGColorSpace
+*/
 kCGColorSpaceSRGB               = "CGColorSpaceSRGB";
 
 var _CGNamedColorSpaces         = {};

AppKit/CoreGraphics/CGContext.j

@@ -41,44 +41,168 @@ kCGPathStroke               = 2;
 kCGPathFillStroke           = 3;
 kCGPathEOFillStroke         = 4;
 
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeNormal          = 0;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeMultiply        = 1;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeScreen          = 2;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeOverlay         = 3;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeDarken          = 4;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeLighten         = 5;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeColorDodge      = 6;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeColorBurn       = 7;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeSoftLight       = 8;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeHardLight       = 9;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeDifference      = 10;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeExclusion       = 11;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeHue             = 12;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeSaturation      = 13;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeColor           = 14;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeLuminosity      = 15;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeClear           = 16;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeCopy            = 17;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeSourceIn        = 18;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeSourceOut       = 19;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeSourceAtop      = 20;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeDestinationOver = 21;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeDestinationIn   = 22;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeDestinationOut  = 23;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeDestinationAtop = 24;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModeXOR             = 25;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModePlusDarker      = 26;
+/*
+    @global
+    @group CGBlendMode
+*/
 kCGBlendModePlusLighter     = 27;
 
+/*
+    This function is just here for source compatability.
+    It does nothing.
+    @group CGContext
+*/
 function CGContextRelease()
 {
 }
 
+/*
+    This function is just here for source compatability.
+    It does nothing.
+    @param aContext a CGContext
+    @return CGContext the context
+*/
 function CGContextRetain(aContext)
 {
     return aContext;
 }
 
+// BEGIN CANVAS IF
 if (!CPFeatureIsCompatible(CPHTMLCanvasFeature))
 {
 
@@ -294,15 +418,26 @@ function CGContextSetShadowWithColor(aContext, aSize, aBlur, aColor)
     gState.shadowColor = aColor;
 }
 
-}
+}   // END CANVAS IF
 
 // GOOD.
-
-function CGContextEOFillPath(aContext, aMode)
+/*
+    Fills in the area of the current path, using the even-odd fill rule.
+    @param aContext the CGContext of the path
+    @return void
+    @group CGContext
+*/
+function CGContextEOFillPath(aContext)
 {
     CGContextDrawPath(aContext, kCGPathEOFill);
 }
 
+/*
+    Fills in the area of the current path, using  the non-zero winding number rule.
+    @param aContext the CGContext of the path
+    @return void
+    @group CGContext
+*/
 function CGContextFillPath(aContext)
 {
     CGContextDrawPath(aContext, kCGPathFill);
@@ -310,6 +445,13 @@ function CGContextFillPath(aContext)
 
 var KAPPA = 4.0 * ((SQRT2 - 1.0) / 3.0);
 
+/*
+    Draws the outline of an ellipse bounded by a rectangle.
+    @param aContext CGContext to draw on
+    @param aRect the rectangle bounding the ellipse
+    @return void
+    @group CGContext
+*/
 function CGContextAddEllipseInRect(aContext, aRect)
 {
 	CGContextBeginPath(aContext);
@@ -332,24 +474,54 @@ function CGContextAddEllipseInRect(aContext, aRect)
 	CGContextClosePath(aContext);
 }
 
-
+/*
+    Fills an ellipse bounded by a rectangle.
+    @param aContext CGContext to draw on
+    @param aRect the rectangle bounding the ellipse
+    @return void
+    @group CGContext
+*/
 function CGContextFillEllipseInRect(aContext, aRect)
 {
     CGContextAddEllipseInRect(aContext, aRect);
     CGContextFillPath(aContext);
 }
 
+/*
+    Strokes an ellipse bounded by the specified rectangle.
+    @param aContext CGContext to draw on
+    @param aRect the rectangle bounding the ellipse
+    @return void
+    @group CGContext
+*/
 function CGContextStrokeEllipseInRect(aContext, aRect)
 {
     CGContextAddEllipseInRect(aContext, aRect);
     CGContextStrokePath(aContext);
 }
 
+/*
+    Paints a line in the current path of the current context.
+    @param aContext CGContext to draw on
+    @return void
+    @group CGContext
+*/
 function CGContextStrokePath(aContext)
 {
     CGContextDrawPath(aContext, kCGPathStroke);
 }
 
+/*
+    Strokes multiple line segments.
+    @param aContext CGContext to draw on
+    @param points an array with an even number of points. The
+    first point is the beginning of the first line segment, the second
+    is the end of the first line segment. The third point is
+    the beginning of second line segment, etc.
+    @param count the number of points in the array
+    @return void
+    @group CGContext
+*/
 function CGContextStrokeLineSegments(aContext, points, count)
 {
     var i = 0;
@@ -368,7 +540,16 @@ function CGContextStrokeLineSegments(aContext, points, count)
     CGContextStrokePath(aContext);
 }
 
-// FIXME: THIS IS WRONG!!!
+
+//FIXME: THIS IS WRONG!!!
+
+/*
+    Sets the current fill color.
+    @param aContext the CGContext
+    @param aColor the new color for the fill
+    @return void
+    @group CGContext
+*/
 
 function CGContextSetFillColor(aContext, aColor)
 {
@@ -376,12 +557,31 @@ function CGContextSetFillColor(aContext, aColor)
         aContext.gState.fillStyle = [aColor cssString];
 }
 
+/*
+    Sets the current stroke color.
+    @param aContext the CGContext
+    @param aColor the new color for the stroke
+    @return void
+    @group CGContext
+*/
 function CGContextSetStrokeColor(aContext, aColor)
 {
     if (aColor)
         aContext.gState.strokeStyle = [aColor cssString];
 }
 
+/*
+    Fills a rounded rectangle.
+    @param aContext the CGContext to draw into
+    @param aRect the base rectangle
+    @param aRadius the distance from the rectange corner to the rounded corner
+    @param ne set it to <code>YES</code> for a rounded northeast corner
+    @param se set it to <code>YES</code> for a rounded southeast corner
+    @param sw set it to <code>YES</code> for a rounded southwest corner
+    @param nw set it to <code>YES</code> for a rounded northwest corner
+    @return void
+    @group CGContext
+*/
 function CGContextFillRoundedRectangleInRect(aContext, aRect, aRadius, ne, se, sw, nw)
 {
     var xMin = _CGRectGetMinX(aRect),

AppKit/CoreGraphics/CGGeometry.j

@@ -65,6 +65,14 @@ _function(CGRectIsNull(aRect))
 
 _function(CGRectContainsPoint(aRect, aPoint))
 
+/*
+    Returns a <code>BOOL</code> indicating whether <objj>CGRect</objj> <code>lhsRect</code>
+    contains <objj>CGRect</objj> <code>rhsRect</code>.
+    @group CGRect
+    @param lhsRect the <objj>CGRect</objj> to test if <code>rhsRect</code> is inside of
+    @param rhsRect the <objj>CGRect</objj> to test if it fits inside <code>lhsRect</code>.
+    @return BOOL <code>YES</code> if <code>rhsRect</code> fits inside <code>lhsRect</code>.
+*/
 function CGRectContainsRect(lhsRect, rhsRect)
 {
     var union = CGRectUnion(lhsRect, rhsRect);
@@ -72,6 +80,13 @@ function CGRectContainsRect(lhsRect, rhsRect)
     return _CGRectEqualToRect(union, lhsRect);
 }
 
+/*
+    Returns <code>YES</code> if the two rectangles intersect
+    @group CGRect
+    @param lhsRect the first <objj>CGRect</objj>
+    @param rhsRect the second <objj>CGRect</objj>
+    @return BOOL <code>YES</code> if the two rectangles have any common spaces, and <code>NO</code>, otherwise.
+*/
 function CGRectIntersectsRect(lhsRect, rhsRect)
 {
     var intersection = CGRectIntersection(lhsRect, rhsRect);
@@ -79,6 +94,13 @@ function CGRectIntersectsRect(lhsRect, rhsRect)
     return !_CGRectIsEmpty(intersection);
 }
 
+/*
+    Makes the origin and size of a <objj>CGRect</objj> all integers. Specifically, by making 
+    the southwest corner the origin (rounded down), and the northeast corner a <objj>CGSize</objj> (rounded up).
+    @param aRect the rectangle to operate on
+    @return CGRect the modified rectangle (same as the input)
+    @group CGRect
+*/
 function CGRectIntegral(aRect)
 {
     aRect = CGRectStandardize(aRect);
@@ -96,6 +118,13 @@ function CGRectIntegral(aRect)
     return aRect;
 }
 
+/*
+    Returns the intersection of the two provided rectangles as a new rectangle.
+    @param lhsRect the first rectangle used for calculation
+    @param rhsRect the second rectangle used for calculation
+    @return CGRect the intersection of the two rectangles
+    @group CGRect
+*/
 function CGRectIntersection(lhsRect, rhsRect)
 {
     var intersection = _CGRectMake(
@@ -109,6 +138,9 @@ function CGRectIntersection(lhsRect, rhsRect)
     return _CGRectIsEmpty(intersection) ? _CGRectMakeZero() : intersection;
 }
 
+/*
+    
+*/
 function CGRectStandardize(aRect)
 {
     var width = _CGRectGetWidth(aRect),