Documented CoreText.

AppKit/CoreText/CTFrame.j

@@ -40,7 +40,10 @@ function _CTFrameCreate(aPath, attributes, lines, attributedString)
 
 _CTFrameCreate.displayName = @"_CTFrameCreate";
 
-// Returns a CPRange
+/*!
+    Returns the range of the frame based on the original string
+    FIX ME: This implementation is wrong
+*/
 function CTFrameGetStringRange(/* CTFrame */ aFrame)
 {
     return CPMakeRange();
@@ -48,7 +51,10 @@ function CTFrameGetStringRange(/* CTFrame */ aFrame)
 
 CTFrameGetStringRange.displayName = @"CTFrameGetStringRange";
 
-// Returns a CPRange
+/*!
+    Returns a range object with the visisble characters
+    FIX ME: THis implementation is wrong
+*/
 function CTFrameGetVisibleStringRange(/* CTFrame */ aFrame)
 {
     return CPMakeRange();
@@ -56,7 +62,9 @@ function CTFrameGetVisibleStringRange(/* CTFrame */ aFrame)
 
 CTFrameGetVisibleStringRange.displayName = @"CTFrameGetVisibleStringRange";
 
-// Returns a CGPath
+/*!
+    Returns the path for the frame.
+*/
 function CTFrameGetPath(/* CTFrame */ aFrame)
 {
     return aFrame.path;
@@ -64,7 +72,9 @@ function CTFrameGetPath(/* CTFrame */ aFrame)
 
 CTFrameGetPath.displayName = @"CTFrameGetPath";
 
-// Returns a CPDictionary
+/*!
+    Returns a dictionary of attributes for the frame.
+*/
 function CTFrameGetFrameAttributes(/* CTFrame */ aFrame)
 {
     return aFrame.frameAttributes;
@@ -72,7 +82,9 @@ function CTFrameGetFrameAttributes(/* CTFrame */ aFrame)
 
 CTFrameGetFrameAttributes.displayName = @"CTFrameGetFrameAttributes";
 
-// Returns an array of CTLines
+/*!
+    Returns the array containing CTLines that make up the frame
+*/
 function CTFrameGetLines(/* CTFrame */ aFrame)
 {
     return aFrame.lines;
@@ -80,7 +92,9 @@ function CTFrameGetLines(/* CTFrame */ aFrame)
 
 CTFrameGetLines.displayName = @"CTFrameGetLines";
 
-// Returns an array of CGPoints
+/*!
+    Returns an array of CGPoints for the origin of each CTLine in the frame
+*/
 function CTFrameGetLineOrigins(/* CTFrame */ aFrame, /* CPRange */ aRange)
 {
     var results = [],
@@ -94,8 +108,10 @@ function CTFrameGetLineOrigins(/* CTFrame */ aFrame, /* CPRange */ aRange)
 
 CTFrameGetLineOrigins.displayName = @"CTFrameGetLineOrigins";
 
-// Returns an array of CTLines
-// Divergent from Cocoa and expensive.
+/*!
+    Returns an array of CTLines for a given range.
+    Divergent from Cocoa and expensive.
+*/
 function CTFrameGetLinesForRange(/* CTFrame */ aFrame, /* CPRange */ lhs)
 {
     var lines = aFrame.lines, results = [];
@@ -116,8 +132,10 @@ function CTFrameGetLinesForRange(/* CTFrame */ aFrame, /* CPRange */ lhs)
 
 CTFrameGetLinesForRange.displayName = @"CTFrameGetLinesForRange";
 
-// Returns a CPRange
-// This is divergent from Cocoa. It's a convenience method used in CPTextView.
+/*!
+    Returns a CPRange
+    This is divergent from Cocoa. It's a convenience method used in CPTextView.
+*/
 function CTFrameGetRangeForPoint(/* CTFrame */ aFrame, /* CGPoint */ aPoint)
 {
     var lines = aFrame.lines, y = aPoint.y;
@@ -143,6 +161,9 @@ function CTFrameGetRangeForPoint(/* CTFrame */ aFrame, /* CGPoint */ aPoint)
 
 CTFrameGetRangeForPoint.displayName = @"CTFrameGetRangeForPoint";
 
+/*!
+    Draws the frame to the graphics context.
+*/
 function CTFrameDraw(/* CTFrame */ aFrame, /* CGContext */ aContext)
 {
     var origin = aFrame.path.start,

AppKit/CoreText/CTFramesetter.j

@@ -24,7 +24,9 @@
 @import "CTTypesetter.j"
 
 
-// Returns a CTFramesetter
+/*!
+    Creates a typesetter with a given CPAttributedString
+*/
 function CTFramesetterCreateWithAttributedString(/* CPAttributedString */ aString)
 {
     return {
@@ -35,7 +37,9 @@ function CTFramesetterCreateWithAttributedString(/* CPAttributedString */ aStrin
 
 CTFramesetterCreateWithAttributedString.displayName = @"CTFramesetterCreateWithAttributedString";
 
-// Returns a CTFrame
+/*!
+    Creates a CTFrame with a given typesetter, range, path, and attributes
+*/
 function CTFramesetterCreateFrame(/* CTFramesetter */ aFramesetter, /* CPRange */ aRange, /* CGPath */ aPath, /* CPDictionary */ frameAttributes)
 {
     if (aFramesetter._cachedFrame && [aFramesetter._cachedAttributes isEqual:frameAttributes])
@@ -73,7 +77,9 @@ function CTFramesetterCreateFrame(/* CTFramesetter */ aFramesetter, /* CPRange *
 
 CTFramesetterCreateFrame.displayName = @"CTFramesetterCreateFrame";
 
-// Returns a CTTypesetter
+/*!
+    Returns a CTTypesetter
+*/
 function CTFramesetterGetTypesetter(/* CTFramesetter */ aFramesetter)
 {
     return aFramesetter.typesetter;
@@ -81,7 +87,9 @@ function CTFramesetterGetTypesetter(/* CTFramesetter */ aFramesetter)
 
 CTFramesetterGetTypesetter.displayName = @"CTFramesetterGetTypesetter";
 
-// Returns a CGSize
+/*!
+    Returns a CGSize object with the suggested size for a given frame.
+*/
 function CTFramesetterSuggestFrameSizeWithConstraints(/* CTFramesetter */ aFramesetter, /* CPRange */ aRange, /* CPDictionary */ frameAttributes, /* CGSize */ constraints, /* {CPRange} */ fitRange)
 {
     var frame = CTFramesetterCreateFrame(aFramesetter, aRange, null, frameAttributes),
@@ -103,6 +111,9 @@ function CTFramesetterSuggestFrameSizeWithConstraints(/* CTFramesetter */ aFrame
 
 CTFramesetterSuggestFrameSizeWithConstraints.displayName = @"CTFramesetterSuggestFrameSizeWithConstraints";
 
+/*!
+    Returns the CPAttributedString for a given framesetter
+*/
 function CTFramesetterGetAttributedString(/* CTFramesetter */ aFramesetter)
 {
     return aFramesetter.string;

AppKit/CoreText/CTLine.j

@@ -27,7 +27,9 @@ kCTLineTruncationStart = 0;
 kCTLineTruncationEnd = 1;
 kCTLineTruncationMiddle = 2;
 
-// Returns a CTLine
+/*!
+    Creates a new line with a supplied CPAttributedString
+*/
 function CTLineCreateWithAttributedString(/* CPAttributedString */ aString)
 {
     var line = {
@@ -42,7 +44,14 @@ function CTLineCreateWithAttributedString(/* CPAttributedString */ aString)
 
 CTLineCreateWithAttributedString.displayName = @"CTLineCreateWithAttributedString";
 
-// Returns a CTLine
+/*!
+    Creates a new line truncated to a given width.
+    @param aLine - The input line
+    @param width - The constraining width
+    @param truncationToken - The characters to represent the truncation. This is usually an elipsis. If not token is given the string will just clip
+
+    FIX ME: Not implemented correctly
+*/
 function CTLineCreateTruncatedLine(/* CTLine */ aLine, /* float */ width, /* CTLineTruncationType */ truncationType, /* CTLine */ truncationToken)
 {
     return aLine;
@@ -50,7 +59,10 @@ function CTLineCreateTruncatedLine(/* CTLine */ aLine, /* float */ width, /* CTL
 
 CTLineCreateTruncatedLine.displayName = @"CTLineCreateTruncatedLine";
 
-// Returns a CTLine
+/*!
+    Returns a CTLine with justified text.
+    FIX ME: This is not implemented correctly
+*/
 function CTLineCreateJustifiedLine(/* CTline */ aLine, /* float */ justificationFactor, /* float */ width)
 {
     return aLine;
@@ -58,7 +70,9 @@ function CTLineCreateJustifiedLine(/* CTline */ aLine, /* float */ justification
 
 CTLineCreateJustifiedLine.displayName = @"CTLineCreateJustifiedLine";
 
-// Returns an index
+/*!
+    Returns the number of glyphs in a given line.
+*/
 function CTLineGetGlyphCount(/* CTLine */ aLine)
 {
     return [aLine.string length];
@@ -66,7 +80,9 @@ function CTLineGetGlyphCount(/* CTLine */ aLine)
 
 CTLineGetGlyphCount.displayName = @"CTLineGetGlyphCount";
 
-// Returns an array of CTGlyphRuns
+/*!
+    Returns the array of CTRuns that make up the line.
+*/
 function CTLineGetGlyphRuns(/* CTLine */ aLine)
 {
     return aLine.runs;
@@ -74,7 +90,9 @@ function CTLineGetGlyphRuns(/* CTLine */ aLine)
 
 CTLineGetGlyphRuns.displayName = @"CTLineGetGlyphRuns";
 
-// Returns a CPRange
+/*!
+    Returns the range for which the CTLine makes up the original string
+*/
 function CTLineGetStringRange(/* CTLine */ aLine)
 {
     return CPCopyRange(aLine.range) || CPMakeRange(0, [aLine.string length])
@@ -82,13 +100,18 @@ function CTLineGetStringRange(/* CTLine */ aLine)
 
 CTLineGetStringRange.displayName = @"CTLineGetStringRange";
 
+/*!
+    No op
+*/
 function CTLineGetPenOffsetForFlush(/* CTLine */ aLine, /* float */ flushFactor, /* float */ flushWidth)
 {
     
 }
 
 CTLineGetPenOffsetForFlush.displayName = @"CTLineGetPenOffsetForFlush";
-
+/*!
+    Draws the CTLine to the graphics context.
+*/
 function CTLineDraw(/* CTLine */ aLine, /* CGContext */ aContext)
 {
     var startPosition = aLine._startPosition = CGContextGetTextPosition(aContext),
@@ -106,8 +129,9 @@ function CTLineDraw(/* CTLine */ aLine, /* CGContext */ aContext)
 
 CTLineDraw.displayName = @"CTLineDraw";
 
-// Returns a CGRect
-// Cheap
+/*!
+    Calcaulates the image bounds for a line.
+*/
 function CTLineGetImageBounds(/* CTLine */ aLine, /* CGContext */ aContext)
 {
     if (aLine._imageBounds)
@@ -129,8 +153,10 @@ function CTLineGetImageBounds(/* CTLine */ aLine, /* CGContext */ aContext)
 
 CTLineGetImageBounds.displayName = @"CTLineGetImageBounds";
 
-// Returns a JSObject: {width: float, ascent: float, descent: float, lineHeight: float}
-// More expensive
+/*!
+    Returns a JSObject: {width: float, ascent: float, descent: float, lineHeight: float}
+    This method is more expensive than CTLineGetImageBounds.
+*/
 function CTLineGetTypographicBounds(/* CTLine */ aLine)
 {
     if (aLine._typographicBounds)
@@ -161,7 +187,9 @@ function CTLineGetTypographicBounds(/* CTLine */ aLine)
 
 CTLineGetTypographicBounds.displayName = @"CTLineGetTypographicBounds";
 
-// Returns an index
+/*!
+    Returns the index of the line based on the original string
+*/
 function CTLineGetStringIndexForPosition(/* CTLine */ aLine, /* CGPoint */ aPoint)
 {
     var runs = aLine.runs, x = aPoint.x, index = 0;
@@ -190,7 +218,10 @@ function CTLineGetStringIndexForPosition(/* CTLine */ aLine, /* CGPoint */ aPoin
 
 CTLineGetStringIndexForPosition.displayName = @"CTLineGetStringIndexForPosition";
 
-// Returns a float
+/*!
+    Returns the offset corresponding to a string index,
+    this works well for for movement between adjacent lines or for drawing a custom caret.  
+*/
 function CTLineGetOffsetForStringIndex(/* CTLine */ aLine, /* int */ anIndex, /* float */ secondaryOffset)
 {
     var runs = aLine.runs;

AppKit/CoreText/CTRun.j

@@ -25,6 +25,10 @@ kCTRunStatusRightToLeft = 1 << 0;
 kCTRunStatusNonMonotonic = 1 << 1;
 kCTRunStatusNonIdentityMatrix = 1 << 2;
 
+/*!
+    A CTRun represents a span of characters with common attribtues.
+*/
+
 function _CTRunCreate(glyphs, attributes)
 {
     return {
@@ -36,7 +40,9 @@ function _CTRunCreate(glyphs, attributes)
 
 _CTRunCreate.displayName = @"_CTRunCreate";
 
-// Returns an index
+/*!
+    Returns the number of glyphs in the run.
+*/
 function CTRunGetGlyphCount(/* CTRun */ aRun)
 {
     return aRun.glyphs.length;
@@ -44,7 +50,9 @@ function CTRunGetGlyphCount(/* CTRun */ aRun)
 
 CTRunGetGlyphCount.displayName = @"CTRunGetGlyphCount";
 
-// Returns a CPDictionary
+/*!
+    Returns a CPDictionary of attributes for the CTRun
+*/
 function CTRunGetAttributes(/* CTRun */ aRun)
 {
     return aRun.attributes;
@@ -52,7 +60,19 @@ function CTRunGetAttributes(/* CTRun */ aRun)
 
 CTRunGetAttributes.displayName = @"CTRunGetAttributes";
 
-// Returns a CTRunStatus (int)
+/*!
+    Returns a CTRunStatus
+    CTRuns have status that can be used to speed up certain operations.
+
+    Possible values:
+
+    @code
+    kCTRunStatusNoStatus
+    kCTRunStatusRightToLeft
+    kCTRunStatusNonMonotonic
+    kCTRunStatusNonIdentityMatrix
+    @endcode
+*/
 function CTRunGetStatus(/* CTRun */ aRun)
 {
     return aRun.status || kCTRunStatusNoStatus;
@@ -60,7 +80,10 @@ function CTRunGetStatus(/* CTRun */ aRun)
 
 CTRunGetStatus.displayName = @"CTRunGetStatus";
 
-// Returns an array of CGGlyphs
+/*!
+    Returns an array of CGGlyphs
+    FIX ME: Not implemented correctly
+*/
 function CTRunGetGlyphs(/* CTRun */ aRun, /* CPRange */ aRange)
 {
     if (!aRun.glyphs)
@@ -71,7 +94,10 @@ function CTRunGetGlyphs(/* CTRun */ aRun, /* CPRange */ aRange)
 
 CTRunGetGlyphs.displayName = @"CTRunGetGlyphs";
 
-// Returns an array of CGPoints
+/*!
+    Returns an array of CGPoints
+    FIX ME: Not implemented correctly
+*/
 function CTRunGetPositions(/* CTRun */ aRun, /* CPRange */ aRange)
 {
     if (!aRun.positions)
@@ -82,7 +108,10 @@ function CTRunGetPositions(/* CTRun */ aRun, /* CPRange */ aRange)
 
 CTRunGetPositions.displayName = @"CTRunGetPositions";
 
-// Returns an array of CGSizes
+/*!
+    Returns an array of CGSizes
+    FIX ME: Not implemented correctly
+*/
 function CTRunGetAdvances(/* CTRun */ aRun, /* CPRange */ aRange)
 {
     if (!aRun.advances)
@@ -93,7 +122,10 @@ function CTRunGetAdvances(/* CTRun */ aRun, /* CPRange */ aRange)
 
 CTRunGetAdvances.displayName = @"CTRunGetAdvances";
 
-// Returns an array of indexes
+/*!
+    Returns an array of indexes.
+    FIX ME: Not implemented correctly
+*/
 function CTRunGetStringIndices(/* CTRun */ aRun, /* CPRange */ aRange)
 {
     if (!aRun.stringIndices)
@@ -104,16 +136,20 @@ function CTRunGetStringIndices(/* CTRun */ aRun, /* CPRange */ aRange)
 
 CTRunGetStringIndices.displayName = @"CTRunGetStringIndices";
 
-// Returns a CPRange
+/*!
+    Returns a CPRange containing the location of the run in the parent string
+*/
 function CTRunGetStringRange(/* CTRun */ aRun)
 {
-    
+    return aRun.range;
 }
 
 CTRunGetStringRange.displayName = @"CTRunGetStringRange";
 
-// Returns a JSObject: {width: float, ascender: float, descender: float, lineHeight: float}
-// More expensive
+/*!
+    Returns a JSObject: {width: float, ascender: float, descender: float, lineHeight: float}
+    More expensive
+*/
 function CTRunGetTypographicBounds(/* CTRun */ aRun, /* CPRange */ aRange)
 {
     if (aRun._typographicBounds)
@@ -133,8 +169,10 @@ function CTRunGetTypographicBounds(/* CTRun */ aRun, /* CPRange */ aRange)
 
 CTRunGetTypographicBounds.displayName = @"CTRunGetTypographicBounds";
 
-// Returns a CGRect
-// Cheap
+/*!
+    Returns a CGRect
+    Cheap
+*/
 function CTRunGetImageBounds(/* CTRun */ aRun, /* CGContext */ aContext, /* CPRange */ aRange)
 {
     if (aRun._imageBounds)
@@ -161,6 +199,9 @@ function CTRunGetTextMatrix(/* CTRun */ aRun)
 
 CTRunGetTextMatrix.displayName = @"CTRunGetTextMatrix";
 
+/*!
+    Draws the run to the context
+*/
 function CTRunDraw(/* CTRun */ aRun, /* CGContext */ aContext, /* CPRange */ aRange)
 {
     _CTRunPrepareDraw(aRun, aContext);