Added more documentation

Completed documentation on

- DTAttributedTextView
- DTAttributedTextContentView
- DTDictationPlaceholderView
- and a few more

Core/Source/DTAttributedTextContentView.h

@@ -30,7 +30,6 @@ extern NSString * const DTAttributedTextContentViewDidFinishLayoutNotification;
  @name Notifications
  */
 
-
 /**
  Called after a layout frame or a part of it is drawn. 
  
@@ -48,10 +47,10 @@ extern NSString * const DTAttributedTextContentViewDidFinishLayoutNotification;
  
  @param attributedTextContentView The content view that drew a layout frame
  @param textBlock The text block
- @param rect The frame within the content view's coordinate system that will be drawn into
+ @param frame The frame within the content view's coordinate system that will be drawn into
  @param context The graphics context that will be drawn into
  @param layoutFrame The layout frame that will be drawn for
- @param returns `YES` is the standard fill of the text block should be drawn, `NO` if it should not
+ @returns `YES` is the standard fill of the text block should be drawn, `NO` if it should not
  */
 - (BOOL)attributedTextContentView:(DTAttributedTextContentView *)attributedTextContentView shouldDrawBackgroundForTextBlock:(DTTextBlock *)textBlock frame:(CGRect)frame context:(CGContextRef)context forLayoutFrame:(DTCoreTextLayoutFrame *)layoutFrame; 
 
@@ -100,13 +99,24 @@ extern NSString * const DTAttributedTextContentViewDidFinishLayoutNotification;
 
 
 enum {
-    DTAttributedTextContentViewRelayoutNever            = 0,
+	DTAttributedTextContentViewRelayoutNever            = 0,
 	DTAttributedTextContentViewRelayoutOnWidthChanged   = 1 << 0,
 	DTAttributedTextContentViewRelayoutOnHeightChanged  = 1 << 1,
 };
 typedef NSUInteger DTAttributedTextContentViewRelayoutMask;
 
 
+/**
+ Attributed Text Content Views display attributed strings generated by DTHTMLAttributedStringBuilder. They can display images and hyperlinks inline or optionally place custom subviews (which get provided via the <delegate> in the appropriate places. By itself content views do not scroll, for that there is the `UIScrollView` subclass <DTAttributedTextView>.
+ 
+ Generally you have two options to providing content:
+ 
+  - set the attributed string
+  - set a layout frame
+ 
+ The first you would normally use, the second you would use if you are layouting a larger text and then simply want to display individual parts (e.g. pages from an e-book) in a content view.
+ */
+
 @interface DTAttributedTextContentView : UIView
 {
 	NSAttributedString *_attributedString;
@@ -119,57 +129,182 @@ typedef NSUInteger DTAttributedTextContentViewRelayoutMask;
 	BOOL _flexibleHeight;
 }
 
-- (void)layoutSubviewsInRect:(CGRect)rect;
-- (void)relayoutText;
-- (void)removeAllCustomViews;
-- (void)removeAllCustomViewsForLinks;
 
-- (CGSize)attributedStringSizeThatFits:(CGFloat)width;
+/**
+ @name Sizing
+ */
+
+/**
+ Calculates the suggested frame size that would fit the entire <attributedString> with a maximum width.
+ 
+ This does a full layout pass that is cached in <DTCoreTextLayouter>. If you specify a frame that fits the result from this method then the resulting layoutFrame is reused.
+ 
+ Since this obeys the <edgeInsets> you have to add these to the final frame size.
+ 
+ @param width The maximum width to layout for
+ @returns The suggested frame size
+ */
 - (CGSize)suggestedFrameSizeToFitEntireStringConstraintedToWidth:(CGFloat)width; // obeys the edge insets
 
+
 /**
  The size of contents of the receiver. This is possibly used by auto-layout, but also for example if you want to get the size of the receiver necessary for a scroll view
  
- This method is defined as of iOS 6, but to support earlier OS versions 
+ This method is defined as of iOS 6, but to support earlier OS versions
  */
 - (CGSize)intrinsicContentSize;
 
-// properties are overwritten with locking to avoid problem with async drawing
+
+/**
+ @name Layouting
+ */
+
+/**
+ Discards the current <layoutFrame> and creates a new one based on the <attributedString>.
+ */
+- (void)relayoutText;
+
+
+/**
+ The layouter to use for the receiver. Created by default.
+ 
+ By default this is generated automatically for the current <attributedString>. You can also supply your own if you require special layouting behavior.
+ */
 @property (atomic, strong) DTCoreTextLayouter *layouter;
+
+
+/**
+ The layout frame to use for the receiver. Created by default.
+ 
+ A layout frame is basically one rectangle, inset by the <edgeInsets>. By default this is automatically generated for the current <attributedString>. You can also create a <DTCoreTextLayoutFrame> seperately and set this property to display the layout frame. This is usedful for example if you layout entire e-book and then set the <layoutFrame> for displaying individual pages.
+ */
 @property (atomic, strong) DTCoreTextLayoutFrame *layoutFrame;
 
-@property (nonatomic, strong) NSMutableSet *customViews;
 
+/**
+ The dispatch queue that is used to serialize layouting actions
+ */
+#if OS_OBJECT_USE_OBJC
+@property (nonatomic, strong) dispatch_queue_t layoutQueue;  // GCD objects use ARC
+#else
+@property (nonatomic, assign) dispatch_queue_t layoutQueue;  // GCD objects don't use ARC
+#endif
+
+/**
+ @name Working with Custom Subviews
+ */
+
+/**
+ Removes all custom subviews (excluding views representing links) from the receiver.
+ */
+- (void)removeAllCustomViews;
+
+
+/**
+ Removes all custom subviews representing links from the receiver
+ */
+- (void)removeAllCustomViewsForLinks;
+
+
+/**
+ Removes invisible custom subviews and lays out subviews visible in the given rectangle
+ @param rect The bounds of the visible area to layout custom subviews in.
+ */
+- (void)layoutSubviewsInRect:(CGRect)rect;
+
+
+/**
+ @name Providing Content
+ */
+
+/**
+ The attributed string to display in the receiver
+ */
 @property (nonatomic, copy) NSAttributedString *attributedString;
+
+
+/**
+ The delegate that is in charge of supplying custom behavior for the receiver. It must conform to <DTAttributedTextContentViewDelegate> and provide custom subviews, link buttons, etc.
+ */
+
+@property (nonatomic, assign) IBOutlet id <DTAttributedTextContentViewDelegate> delegate;	// subtle simulator bug - use assign not __unsafe_unretained
+
+
+/**
+ @name Customizing Content Display
+ */
+
+/**
+ The insets to apply around the text content
+ */
 @property (nonatomic) UIEdgeInsets edgeInsets;
+
+
+/**
+ Specifies if the receiver should draw image text attachments. 
+ 
+ Set to `NO` if you use the delegate methods to provide custom subviews to display images.
+ */
 @property (nonatomic) BOOL shouldDrawImages;
+
+
+/**
+ Specified if the receiver should draw hyperlinks. 
+ 
+ If set to `NO` then your custom subview/button for hyperlinks is responsible for displaying hyperlinks. You can use <DTLinkButton> to have links show a differently for normal and highlighted style
+ */
 @property (nonatomic) BOOL shouldDrawLinks;
+
+
+/**
+ Specifies if the receiver should layout custom subviews in layoutSubviews. 
+ 
+ If set to `YES` then all custom subviews will always be layouted. Set to `NO` to only layout visible subviews, e.g. in a scroll view. Defaults to `YES` if used stand-alone, `NO` inside a <DTAttributedTextView>.
+ */
 @property (nonatomic) BOOL shouldLayoutCustomSubviews;
+
+
+/**
+ The amount by which all contents of the receiver will offset of display and subview layouting
+ */
 @property (nonatomic) CGPoint layoutOffset;
+
+
+/**
+ The offset to apply for drawing the background. 
+ 
+ If you set a pattern color as background color you can have the pattern phase be offset by this value.
+ */
 @property (nonatomic) CGSize backgroundOffset;
 
+
 /**
  An integer bit mask that determines how the receiver relayouts its contents when its bounds change.
  
  When the view’s bounds change, that view automatically re-layouts its text according to the relayout mask. You specify the value of this mask by combining the constants described in DTAttributedTextContentViewRelayoutMask using the C bitwise OR operator. Combining these constants lets you specify which dimensions will cause a re-layout if modified. The default value of this property is DTAttributedTextContentViewRelayoutOnWidthChanged, which indicates that the text will be re-layouted if the width changes, but not if the height changes.
  */
 @property (nonatomic) DTAttributedTextContentViewRelayoutMask relayoutMask;
 
-@property (nonatomic, assign) IBOutlet id <DTAttributedTextContentViewDelegate> delegate;	// subtle simulator bug - use assign not __unsafe_unretained
-
-#if OS_OBJECT_USE_OBJC
-@property (nonatomic, strong) dispatch_queue_t layoutQueue;  // GCD objects use ARC
-#else
-@property (nonatomic, assign) dispatch_queue_t layoutQueue;  // GCD objects don't use ARC
-#endif
-
-
 @end
 
 
+/**
+ You can globally customize the layer class to be used for new instances of <DTAttributedTextContentView>. By itself it makes most sense to go with the default `CALayer`. For larger bodies of text, i.e. if there is scrolling then you should use a `CATiledLayer` subclass instead.
+ */
 @interface DTAttributedTextContentView (Tiling)
 
+/**
+ Sets the layer class globally to use in new instances of content views. Defaults to `CALayer`.
+ 
+ While being fine for most use cases you should use a `CATiledLayer` subclass for anything larger than a screen full, e.g. in scroll views.
+ @param layerClass The class to use, should be a `CALayer` subclass
+ */
 + (void)setLayerClass:(Class)layerClass;
+
+/**
+ The current layer class that is used for new instances
+ @returns The `CALayer` subclass that new instances are using
+ */
 + (Class)layerClass;
 
 @end

Core/Source/DTAttributedTextContentView.m

@@ -49,10 +49,11 @@ @interface DTAttributedTextContentView ()
 
 @property (nonatomic, strong) NSMutableDictionary *customViewsForLinksIndex;
 @property (nonatomic, strong) NSMutableDictionary *customViewsForAttachmentsIndex;
+@property (nonatomic, strong) NSMutableSet *customViews;
 
 - (void)removeAllCustomViews;
-- (void)removeSubviewsOutsideRect:(CGRect)rect;
 - (void)removeAllCustomViewsForLinks;
+- (void)removeSubviewsOutsideRect:(CGRect)rect;
 
 @end
 
@@ -555,17 +556,6 @@ - (CGSize)suggestedFrameSizeToFitEntireStringConstraintedToWidth:(CGFloat)width
 	return CGSizeMake(tmpLayoutFrame.frame.size.width + _edgeInsets.left + _edgeInsets.right, CGRectGetMaxY(tmpLayoutFrame.frame) + _edgeInsets.bottom);
 }
 
-- (CGSize)attributedStringSizeThatFits:(CGFloat)width
-{
-	if (!isnormal(width))
-	{
-		width = self.bounds.size.width;
-	}
-
-	// attributedStringSizeThatFits: returns an unreliable measure prior to 4.2 for very long documents.
-	return [self.layouter suggestedFrameSizeToFitEntireStringConstraintedToWidth:width-_edgeInsets.left-_edgeInsets.right];
-}
-
 #pragma mark Properties
 - (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
 {
@@ -656,6 +646,16 @@ - (void)setShouldDrawImages:(BOOL)shouldDrawImages
 	}
 }
 
+- (void)setShouldDrawLinks:(BOOL)shouldDrawLinks
+{
+	if (_shouldDrawLinks != shouldDrawLinks)
+	{
+		_shouldDrawLinks = shouldDrawLinks;
+
+		[self setNeedsDisplay];
+	}
+}
+
 - (void)setBackgroundColor:(DTColor *)newColor
 {
 	super.backgroundColor = newColor;

Core/Source/DTAttributedTextView.h

@@ -10,13 +10,32 @@
 
 @class DTAttributedTextView;
 
+/**
+ This view is designed to be a replacement for `UITextView`. It is a `UIScrollView` subclass and creates a <DTAttributedTextContentView> as content view for displaying the text
+ */
+
 @interface DTAttributedTextView : UIScrollView
 
+/**
+ @name Providing Content
+ */
+
 /**
  The attributed text to be displayed in the text content view of the receiver.
  */
 @property (nonatomic, strong) NSAttributedString *attributedString;
 
+
+/**
+ A delegate implementing DTAttributedTextContentViewDelegate to provide custom subviews for images and links.
+ */
+@property (nonatomic, unsafe_unretained) IBOutlet id <DTAttributedTextContentViewDelegate> textDelegate;
+
+
+/**
+ @name Accessing Subviews
+ */
+
 /**
  References to the DTAttributedTextContentView that display the text. This is not named contentView because this class inherits from `UIScrollView` which has an internal property of this name
  */
@@ -27,16 +46,21 @@
  */
 @property (nonatomic, strong) IBOutlet UIView *backgroundView;
 
+
 /**
- A delegate implementing DTAttributedTextContentViewDelegate to provide custom subviews for images and links.
+ @name Customizing Display
  */
-@property (nonatomic, unsafe_unretained) IBOutlet id <DTAttributedTextContentViewDelegate> textDelegate;
 
 /**
  If the content view of the receiver should draw links. Set to `NO` if displaying links as custom views via textDelegate;
  */
 @property (nonatomic, assign) BOOL shouldDrawLinks;
 
+
+/**
+ @name User Interaction
+ */
+
 /**
  Scrolls the receiver to the anchor with the given name to the top.
  @param anchorName The name of the href anchor.

Core/Source/DTCoreTextLayoutFrame.h

@@ -107,15 +107,14 @@ typedef void (^DTCoreTextLayoutFrameTextBlockHandler)(DTTextBlock *textBlock, CG
  
  @param context A graphics context to draw into
  @param drawImages Whether images should be drawn together with the text. If you specify `NO` then space is left blank where images would go and you have to add your own views to display these images.
+ @param drawLinks Whether hyperlinks should be drawn together with the text. If you specify `NO` then space is left blank where links would go and you have to add your own views to display these images.
  @param drawImages Whether hyperlinks should be drawn together with the text. If you specify `NO` then space is left blank where links would go and you have to add your own views to display these links.
  */
 - (void)drawInContext:(CGContextRef)context drawImages:(BOOL)drawImages drawLinks:(BOOL)drawLinks;
 
 
 /**
- Set a custom handler to be executed before text belonging to a text block is drawn.
- 
- @param handler A DTCoreTextLayoutFrameTextBlockHandler block.
+ Set a custom handler to be executed before text belonging to a text block is drawn. Of type <DTCoreTextLayoutFrameTextBlockHandler>.
 */
 @property (nonatomic, copy) DTCoreTextLayoutFrameTextBlockHandler textBlockHandler;
 

Core/Source/DTDictationPlaceholderView.h

@@ -8,6 +8,10 @@
 
 #import <UIKit/UIKit.h>
 
+/**
+ A dictation placeholder to display in editors between the time the recording is complete until a recognized response is received.
+ */
+
 @interface DTDictationPlaceholderView : UIView
 
 /**

Core/Source/DTHTMLElementAttachment.h

@@ -8,6 +8,10 @@
 
 #import "DTHTMLElement.h"
 
+/**
+ Specialized subclass of <DTHTMLElement> for dealing with <DTTextAttachment> instances, e.g. images.
+ */
+
 @interface DTHTMLElementAttachment : DTHTMLElement
 
 @end