Permalink
Browse files

Updated docs style

  • Loading branch information...
1 parent 03de957 commit 43f2bf8dae905999de903d3a2e8ede73666e7ce7 @odrobnik odrobnik committed Mar 3, 2012
View
@@ -8,30 +8,41 @@
#if TARGET_OS_IPHONE
+/**
+ Methods used to work with HTML representations of colors.
+ */
@interface UIColor (HTML)
typedef UIColor DTColor;
-/** Takes a CSS color string ('333', 'F9FFF9'), determines the RGB values used, and returns a UIColor object of that color.
+/**
+ Takes a CSS color string ('333', 'F9FFF9'), determines the RGB values used, and returns a UIColor object of that color.
For each part of the RGB color those numbers for that color are converted to a number using a category on NSString. Then that number is divided by the maximum value, 15 for 3 character strings and 255 for 6 character strings, making the color a percentage and within the range 0.0 and 1.0 that UIColor uses.
@param hex A CSS hexadecimal color string of length 6 or 3.
- @return A UIColor object generated from the hexadecimal color string with alpha 1.0. */
+ @returns A UIColor object generated from the hexadecimal color string with alpha 1.0.
+ */
+ (UIColor *)colorWithHexString:(NSString *)hex;
-/** Takes an English string representing a color and maps it to a numeric RGB value as declared by the HTML and CSS specifications (see http://www.w3schools.com/html/html_colornames.asp). Also accepts CSS `#` hexadecimal colors, `rgba`, and `rgb` and does the right thing returning a corresponding UIColor.
+/**
+ Takes an English string representing a color and maps it to a numeric RGB value as declared by the HTML and CSS specifications (see http://www.w3schools.com/html/html_colornames.asp). Also accepts CSS `#` hexadecimal colors, `rgba`, and `rgb` and does the right thing returning a corresponding UIColor.
If a color begins with a `#` we know that it is a hexadecimal color and send it to colorWithHexString:. If the string is an `rgba()` color declaration the comma delimited r, g, b, and a values are made into percentages and then made into a UIColor which is returned. If the string is an `rgb()` color declaration the same process happens except with an alpha of 1.0.
The last case is that the color string is not a numeric declaration `#`, nor a `rgba` or `rgb` declaration so the CSS color value matching the English string is found in a lookup dictionary and then passed to colorWithHexString: which will make a UIColor out of the hexadecimal string.
@param name The CSS color string that we want to map from a name into an RGB color.
- @return A UIColor object representing the name parameter as numeric values declared by the HTML and CSS specifications, a `rgba()` color, or a `rgb()` color. */
+ @returns A UIColor object representing the name parameter as numeric values declared by the HTML and CSS specifications, a `rgba()` color, or a `rgb()` color.
+ */
+ (UIColor *)colorWithHTMLName:(NSString *)name;
-/** Return a string hexadecimal representation of this UIColor. Splits the color into components with CGColor methods, re-maps them from percentages to the range 0-255, and depending on the number of components returns a grayscale (repeating string of two characters) or color RGB (alpha is stripped) six character string. In the event of a non-2 or non-4 component color nil is returned as it is from an unsupported color space.
- @return A CSS hexadecimal NSString specifying this UIColor. */
+/**
+ Return a string hexadecimal representation of this UIColor. Splits the color into components with CGColor methods, re-maps them from percentages to the range 0-255, and depending on the number of components returns a grayscale (repeating string of two characters) or color RGB (alpha is stripped) six character string. In the event of a non-2 or non-4 component color nil is returned as it is from an unsupported color space.
+ @returns A CSS hexadecimal NSString specifying this UIColor.
+ */
- (NSString *)htmlHexString;
-/** A quick method to return the alpha component of this UIColor by using the CGColorGetAlpha method.
- @return The floating point alpha value of this UIColor. */
+/**
+ A quick method to return the alpha component of this UIColor by using the CGColorGetAlpha method.
+ @returns The floating point alpha value of this UIColor.
+ */
- (CGFloat)alphaComponent;
@end
@@ -40,32 +51,50 @@ typedef UIColor DTColor;
typedef NSColor DTColor;
+/**
+ Methods used to work with HTML representations of colors.
+ */
@interface NSColor (HTML)
-/** Takes a CSS color string ('333', 'F9FFF9'), determines the RGB values used, and returns an NSColor object of that color.
+
+/**
+ Takes a CSS color string ('333', 'F9FFF9'), determines the RGB values used, and returns an NSColor object of that color.
For each part of the RGB color those numbers for that color are converted to a number using a category on NSString. Then that number is divided by the maximum value, 15 for 3 character strings and 255 for 6 character strings, making the color a percentage and within the range 0.0 and 1.0 that NSColor uses.
@param hex A CSS hexadecimal color string of length 6 or 3.
- @return An NSColor object generated from the hexadecimal color string with alpha 1.0. */
+ @returns An NSColor object generated from the hexadecimal color string with alpha 1.0.
+ */
+ (NSColor *)colorWithHexString:(NSString *)hex;
-/** Takes an English string representing a color and maps it to a numeric RGB value as declared by the HTML and CSS specifications (see http://www.w3schools.com/html/html_colornames.asp). Also accepts CSS `#` hexadecimal colors, `rgba`, and `rgb` and does the right thing returning a corresponding NSColor.
+
+/**
+ Takes an English string representing a color and maps it to a numeric RGB value as declared by the HTML and CSS specifications (see http://www.w3schools.com/html/html_colornames.asp). Also accepts CSS `#` hexadecimal colors, `rgba`, and `rgb` and does the right thing returning a corresponding NSColor.
If a color begins with a `#` we know that it is a hexadecimal color and send it to colorWithHexString:. If the string is an `rgba()` color declaration the comma delimited r, g, b, and a values are made into percentages and then made into an NSColor which is returned. If the string is an `rgb()` color declaration the same process happens except with an alpha of 1.0.
The last case is that the color string is not a numeric declaration `#`, nor a `rgba` or `rgb` declaration so the CSS color value matching the English string is found in a lookup dictionary and then passed to colorWithHexString: which will make an NSColor out of the hexadecimal string.
@param name The CSS color string that we want to map from a name into an RGB color.
- @return An NSColor object representing the name parameter as numeric values declared by the HTML and CSS specifications, a `rgba()` color, or a `rgb()` color. */
+ @returns An NSColor object representing the name parameter as numeric values declared by the HTML and CSS specifications, a `rgba()` color, or a `rgb()` color.
+ */
+ (NSColor *)colorWithHTMLName:(NSString *)name;
-/** Return a string hexadecimal representation of this NSColor. Splits the color into components with CGColor methods, re-maps them from percentages in the range 0-255, and returns the RGB color (alpha is stripped) in a six character string.
- @return A CSS hexadecimal NSString specifying this NSColor. */
+
+/**
+ Return a string hexadecimal representation of this NSColor. Splits the color into components with CGColor methods, re-maps them from percentages in the range 0-255, and returns the RGB color (alpha is stripped) in a six character string.
+ @returns A CSS hexadecimal NSString specifying this NSColor.
+ */
- (NSString *)htmlHexString;
-/** Converts a CGColorRef into an NSColor by placing each component into an NSColor and pending on the component count to return a grayscale or rgb color. If there are not 2 (grayscale) or 4 (rgba) components the color is from an unsupported color space and nil is returned.
- @return An NSColor of this CGColorRef */
+
+/**
+ Converts a CGColorRef into an NSColor by placing each component into an NSColor and pending on the component count to return a grayscale or rgb color. If there are not 2 (grayscale) or 4 (rgba) components the color is from an unsupported color space and nil is returned.
+ @param cgColor The CGColorRef to convert
+ @returns An NSColor of this CGColorRef
+ */
+ (NSColor *)colorWithCGColor:(CGColorRef)cgColor;
-/** Pass through.
- @return This color. Returns self. */
+/**
+ Pass through method. This is used for unit testing
+ @returns This color. Returns self.
+ */
- (NSColor *)CGColor;
@end
View
@@ -4,10 +4,16 @@
typedef UIImage DTImage;
+/**
+ Category used to have the same method available for unit testing on Mac on iOS.
+ */
@interface UIImage (HTML)
-/** Retrieve the NSData representation of a UIImage. Used to encode UIImages in DTTextAttachments.
- @return The NSData repreentation of the UIImage instance receiving this message. Convenience method for UIImagePNGRepresentation(). */
+/**
+ Retrieve the NSData representation of a UIImage. Used to encode UIImages in DTTextAttachments.
+
+ @returns The NSData representation of the UIImage instance receiving this message. Convenience method for UIImagePNGRepresentation().
+ */
- (NSData *)dataForPNGRepresentation;
@end
@@ -16,10 +22,17 @@ typedef UIImage DTImage;
typedef NSImage DTImage;
+/**
+ Category used to have the same method available for unit testing on Mac on iOS.
+ */
@interface NSImage (HTML)
-/** Retrieve the NSData representation of a NSImage.
- @return The NSData repreentation of the NSImage instance receiving this message. */
+
+/**
+ Retrieve the NSData representation of a NSImage.
+
+ @returns The NSData representation of the NSImage instance receiving this message.
+ */
- (NSData *)dataForPNGRepresentation;
@end
@@ -8,27 +8,44 @@
#import <Foundation/Foundation.h>
-/** Category on NSCharacterSet to create character sets frequently used and relevant to HTML and CSS string manipulations. Each character set is only initialized once. */
+/**
+ Category on NSCharacterSet to create character sets frequently used and relevant to HTML and CSS string manipulations. Each character set is only initialized once.
+ */
@interface NSCharacterSet (HTML)
-/** Creates an alpha-numeric character set, appropriate for tag names.
- @return An NSCharacterSet with alpha-numeric characters. a-Z, 0-9. */
+
+/**
+ Creates an alpha-numeric character set, appropriate for tag names.
+ @returns An NSCharacterSet with alpha-numeric characters. a-Z, 0-9.
+ */
+ (NSCharacterSet *)tagNameCharacterSet;
-/** Creates an alpha-numeric character set just as tagNameCharacterSet does but also with colon, dash, and underscore characters, appropriate for tag attribute names.
- @return An NSCharacterSet with alpha-numeric characters and colon :, dash -, and underscore _'. */
+
+/**
+ Creates an alpha-numeric character set just as tagNameCharacterSet does but also with colon, dash, and underscore characters, appropriate for tag attribute names.
+ @returns An NSCharacterSet with alpha-numeric characters and colon :, dash -, and underscore _'.
+ */
+ (NSCharacterSet *)tagAttributeNameCharacterSet;
-/** Creates a character set with the apostrophe character ' (used as single quote agnostic of direction) and double quote character " (agnostic of direction).
- @return An NSCharacterSet with the single quote and double quote characters: ', ". */
+
+/**
+ Creates a character set with the apostrophe character ' (used as single quote agnostic of direction) and double quote character " (agnostic of direction).
+ @returns An NSCharacterSet with the single quote and double quote characters: ', ".
+ */
+ (NSCharacterSet *)quoteCharacterSet;
-/** Creates a character set with the characters forward slash / and closing angle bracket aka greater than sign >, then forms the union of this character set with the [whitespace character set](https://developer.apple.com/library/ios/#documentation/Cocoa/Reference/Foundation/Classes/NSCharacterSet_Class/Reference/Reference.html) which includes space, tab, newline, and nextline characters. Useful to find the end of an attribute.
- @return An NSCharacterSet with the forward slash, closing angle bracket characters, tab, space, newline, and nextline characters. */
+
+/**
+ Creates a character set with the characters forward slash / and closing angle bracket aka greater than sign >, then forms the union of this character set with the [whitespace character set](https://developer.apple.com/library/ios/#documentation/Cocoa/Reference/Foundation/Classes/NSCharacterSet_Class/Reference/Reference.html) which includes space, tab, newline, and nextline characters. Useful to find the end of an attribute.
+ @returns An NSCharacterSet with the forward slash, closing angle bracket characters, tab, space, newline, and nextline characters.
+ */
+ (NSCharacterSet *)nonQuotedAttributeEndCharacterSet;
-/** Creates an alpha-numeric character set just as tagNameCharacterSet does but also with the dash and underscore characters. Does not contain the colon character because it will mess up parsing of CSS style attributes. Useful for CSS attribute names.
- @return An NSCharacterSet with alpha-numeric characters, dash, and underscore characters. */
+
+/**
+ Creates an alpha-numeric character set just as tagNameCharacterSet does but also with the dash and underscore characters. Does not contain the colon character because it will mess up parsing of CSS style attributes. Useful for CSS attribute names.
+ @returns An NSCharacterSet with alpha-numeric characters, dash, and underscore characters.
+ */
+ (NSCharacterSet *)cssStyleAttributeNameCharacterSet;
@end
@@ -33,14 +33,23 @@ char *NewDTBase64Encode(
bool separateLines,
size_t *outputLength);
+/**
+ Category to deal with base64-strings.
+*/
@interface NSData (DTBase64)
-/** Retrieve the NSData of a string encoded in Base64 encoding.
- @return An NSData representation of a string that was Base64 encoded. */
+/**
+ Retrieve the NSData of a string encoded in Base64 encoding.
+ @param aString The base 64 string.
+ @returns An NSData representation of a string that was Base64 encoded.
+ */
+ (NSData *)dataFromBase64String:(NSString *)aString;
-/** Retrive an NSString in Base64 encoding from an NSData object.
- @return An NSString representation of this NSData instance, encoded in Base64. */
+
+/**
+ Retrive an NSString in Base64 encoding from an NSData object.
+ @returns An NSString representation of this NSData instance, encoded in Base64.
+ */
- (NSString *)base64EncodedString;
@end
@@ -10,20 +10,27 @@
@class DTCoreTextParagraphStyle, DTCoreTextFontDescriptor;
+/**
+ Methods for appending `NSString` instances to mutable attributed strings
+ */
@interface NSMutableAttributedString (HTML)
-/** Appends a string with the same attributes as this string to this string.
+/**
+ Appends a string with the same attributes as this string to this string.
@param string The string to be appended to this string. */
- (void)appendString:(NSString *)string;
-/** Appends a string with a given paragraph style and font to this string.
+/**
+ Appends a string with a given paragraph style and font to this string.
@param string The string to be appended to this string.
@param paragraphStyle Paragraph style to be attributed to the appended string.
@param fontDescriptor Font descriptor to be attributed to the appended string. */
- (void)appendString:(NSString *)string withParagraphStyle:(DTCoreTextParagraphStyle *)paragraphStyle fontDescriptor:(DTCoreTextFontDescriptor *)fontDescriptor;
-/** Appends a string without any attributes.
- @param The string to be appended to this string without any attributes. */
+/**
+ Appends a string without any attributes.
+ @param string The string to be appended to this string without any attributes.
+ */
- (void)appendNakedString:(NSString *)string;
@end
@@ -6,11 +6,15 @@
// Copyright (c) 2012 Drobnik.com. All rights reserved.
//
-#import <Foundation/Foundation.h>
+/**
+ Categories needed for modifying mutable strings, as needed for DTCoreText.
+ */
@interface NSMutableString (HTML)
-/** Removes the trailing whitespace from this NSMutableString instance. */
+/**
+ Removes the trailing whitespace from the receiver.
+ */
- (void)removeTrailingWhitespace;
@end
View
@@ -9,27 +9,39 @@
#import "DTCoreText.h"
#import "DTColor+HTML.h"
-/** Methods to make dealing with CSS strings easier. Extract shadows from this string, extract CSS styles found in this string, extract the pixel size of a CSS measurement relative to the current text size, and extract the CSS pixel measurement of this string.
+/**
+ Methods to make dealing with CSS strings easier. Extract shadows from this string, extract CSS styles found in this string, extract the pixel size of a CSS measurement relative to the current text size, and extract the CSS pixel measurement of this string.
*/
@interface NSString (CSS)
-/** Examine a string for all CSS styles that are applied to it and return a dictionary of those styles. Implemented using scanCSSAttribute: which is defined in NSScanner+HTML.h.
- @return A dictionary of strings containing the CSS styles which are applied to this string. */
+/**
+ Examine a string for all CSS styles that are applied to it and return a dictionary of those styles. Implemented using scanCSSAttribute: which is defined in NSScanner+HTML.h.
+ @returns A dictionary of strings containing the CSS styles which are applied to this string.
+ */
- (NSDictionary *)dictionaryOfCSSStyles;
-/** Takes a textSize and modifies the current string's pixel measurement to be modified by it. Used in DTHTMLElement.
+
+/**
+ Takes a textSize and modifies the current string's pixel measurement to be modified by it. Used in DTHTMLElement.
@param textSize The current size which the CSS size is relative to.
- @return A float that is the size textSize be it %, em or just numbers .*/
+ @returns A float that is the size textSize be it %, em or just numbers .
+ */
- (CGFloat)pixelSizeOfCSSMeasureRelativeToCurrentTextSize:(CGFloat)textSize;
-/** Parse CSS shadow styles, consisting of color, blur, and offset, out of this string. The input string must be comma delimited in the format: <length> <length> <length>? <color>? where the third length and the color are not required per CSS shadows. To calculate the sizes of the blur and offset pixelSizeOfCSSMeasureRelativeToCurrentTextSize is used. Used in DTHTMLElement.
+
+/**
+ Parse CSS shadow styles, consisting of color, blur, and offset, out of this string. The input string must be comma delimited in the format: <length> <length> <length>? <color>? where the third length and the color are not required per CSS shadows. To calculate the sizes of the blur and offset pixelSizeOfCSSMeasureRelativeToCurrentTextSize is used. Used in DTHTMLElement.
@param textSize In order to determine the shadow offset we need what text size it will be displayed at.
@param color Used if no shadow attribute color is found.
- @return An array of dictionaries, each of which is a shadow consisting of color, blur, and offset keys value pairs. */
+ @returns An array of dictionaries, each of which is a shadow consisting of color, blur, and offset keys value pairs.
+ */
- (NSArray *)arrayOfCSSShadowsWithCurrentTextSize:(CGFloat)textSize currentColor:(DTColor *)color;
-/** If this string ends with 'px' return the float value stored therein. Ex: The following '17.0px;' will return 17.0. I DON'T KNOW WHAT USES THIS METHOD IF ANYTHING AT ALL-grep returned just this class
- @return The float value stored in this string. */
+
+/**
+ If this string ends with 'px' return the float value stored therein. Ex: The following '17.0px;' will return 17.0. I DON'T KNOW WHAT USES THIS METHOD IF ANYTHING AT ALL-grep returned just this class
+ @returns The float value stored in this string.
+ */
- (CGFloat)CSSpixelSize;
-@end
+@end
Oops, something went wrong.

0 comments on commit 43f2bf8

Please sign in to comment.