v4.1.1

AppledocSettings.plist

@@ -5,7 +5,7 @@
 	<key>--project-name</key>
 	<string>GRMustache</string>
 	<key>--project-version</key>
-	<string>4.1</string>
+	<string>4.1.1</string>
 	<key>--project-company</key>
 	<string>Gwendal Roué</string>
 	<key>--create-html</key>

include/GRMustache.h

@@ -24,9 +24,9 @@
 #import "GRMustacheAvailabilityMacros.h"
 
 /**
- A C struct that hold GRMustache version information
- 
- @since v1.0
+ * A C struct that hold GRMustache version information
+ * 
+ * @since v1.0
  */
 typedef struct {
     int major;    /**< The major component of the version. */
@@ -36,9 +36,10 @@ typedef struct {
 
 
 /**
- The GRMustache class provides with global-level information and configuration
- of the GRMustache library.
- @since v1.0
+ * The GRMustache class provides with global-level information and configuration
+ * of the GRMustache library.
+ *
+ * @since v1.0
  */
 @interface GRMustache: NSObject
 
@@ -47,10 +48,9 @@ typedef struct {
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- Returns the version of GRMustache as a GRMustacheVersion struct.
- 
- @return The version of GRMustache as a GRMustacheVersion struct.
- @since v1.0
+ * @return The version of GRMustache as a GRMustacheVersion struct.
+ *
+ * @since v1.0
  */
 + (GRMustacheVersion)version AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 
@@ -59,21 +59,32 @@ typedef struct {
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- Have GRMustache raise much less `NSUndefinedKeyExceptions` when rendering templates.
- 
- The rendering of a GRMustache template can lead to many `NSUndefinedKeyExceptions` to be raised, because of the heavy usage of Key-Value Coding. Those exceptions are nicely handled by GRMustache, and are part of the regular rendering of a template.
- 
- Unfortunately, when debugging a project, developers usually set their debugger to stop on every Objective-C exceptions. GRMustache rendering can thus become a huge annoyance. This method prevents it.
- 
- You'll get a slight performance hit, so you'd probably make sure this call does not enter your Release configuration.
- 
- One way to achieve this is to add `-DDEBUG` to the "Other C Flags" setting of your development configuration, and to wrap the `preventNSUndefinedKeyExceptionAttack` method call in a #if block, like:
- 
-    #ifdef DEBUG
-    [GRMustache preventNSUndefinedKeyExceptionAttack];
-    #endif
- 
- @since v1.7
+ * Have GRMustache avoid most `NSUndefinedKeyExceptions` when rendering
+ * templates.
+ * 
+ * The rendering of a GRMustache template can lead to many
+ * `NSUndefinedKeyExceptions` to be raised, because of the heavy usage of
+ * Key-Value Coding. Those exceptions are nicely handled by GRMustache, and are
+ * part of the regular rendering of a template.
+ * 
+ * Unfortunately, when debugging a project, developers usually set their
+ * debugger to stop on every Objective-C exceptions. GRMustache rendering can
+ * thus become a huge annoyance. This method prevents it.
+ * 
+ * You'll get a slight performance hit, so you'd probably make sure this call
+ * does not enter your Release configuration.
+ * 
+ * One way to achieve this is to add `-DDEBUG` to the "Other C Flags" setting of
+ * your development configuration, and to wrap the
+ * `preventNSUndefinedKeyExceptionAttack` method call in a #if block, like:
+ * 
+ *     #ifdef DEBUG
+ *     [GRMustache preventNSUndefinedKeyExceptionAttack];
+ *     #endif
+ * 
+ * **Companion guide:** https://github.com/groue/GRMustache/blob/master/Guides/runtime/context_stack.md
+ * 
+ * @since v1.7
  */
 + (void)preventNSUndefinedKeyExceptionAttack AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 

include/GRMustacheError.h

@@ -25,29 +25,29 @@
 
 
 /**
- The domain of a GRMustache-generated NSError
- 
- @since v1.0
+ * The domain of a GRMustache-generated NSError
+ * 
+ * @since v1.0
  */
 extern NSString* const GRMustacheErrorDomain AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 
 /**
- The codes of a GRMustache-generated NSError
- 
- @since v1.0
+ * The codes of a GRMustache-generated NSError
+ * 
+ * @since v1.0
  */
 typedef enum {
     /**
-     The error code for parse errors.
-     
-     @since v1.0
+     * The error code for parse errors.
+     * 
+     * @since v1.0
      */
     GRMustacheErrorCodeParseError,
 
     /**
-     The error code for not found templates and partials.
-     
-     @since v1.0
+     * The error code for not found templates and partials.
+     * 
+     * @since v1.0
      */
     GRMustacheErrorCodeTemplateNotFound,
 } GRMustacheErrorCode AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;

include/GRMustacheHelper.h

@@ -29,8 +29,36 @@
 // =============================================================================
 #pragma mark - <GRMustacheHelper>
 
+/**
+ * The protocol for implementing Mustache "lambda" sections.
+ *
+ * The responsability of a GRMustacheHelper is to render a Mustache section such
+ * as `{{#bold}}...{{/bold}}`.
+ *
+ * When the data given to a Mustache section is a GRMustacheHelper, GRMustache
+ * invokes the `renderSection:` method of the helper, and inserts the raw return
+ * value in the template rendering.
+ *
+ * **Companion guide:** https://github.com/groue/GRMustache/blob/master/Guides/runtime/helpers.md
+ *
+ * @since v1.9
+ */
 @protocol GRMustacheHelper<NSObject>
 @required
+
+////////////////////////////////////////////////////////////////////////////////
+/// @name Rendering Sections
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Returns the rendering of a Mustache section.
+ *
+ * @param section   The section to render
+ *
+ * @return The rendering of the section
+ *
+ * @since v2.0
+ */
 - (NSString *)renderSection:(GRMustacheSection *)section AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 @end
 
@@ -40,7 +68,32 @@
 
 #if NS_BLOCKS_AVAILABLE
 
+/**
+ * The GRMustacheHelper class helps building mustache helpers without writing a
+ * custom class that conforms to the GRMustacheHelper protocol.
+ *
+ * **Companion guide:** https://github.com/groue/GRMustache/blob/master/Guides/runtime/helpers.md
+ *
+ * @see GRMustacheHelper protocol
+ *
+ * @since v2.0
+ */ 
 @interface GRMustacheHelper: NSObject<GRMustacheHelper>
+
+////////////////////////////////////////////////////////////////////////////////
+/// @name Creating helper objects
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Returns a GRMustacheHelper object that executes the provided block when
+ * rendering a section.
+ *
+ * @param block   The block that renders a section.
+ *
+ * @return a GRMustacheHelper object.
+ *
+ * @since v2.0
+ */
 + (id)helperWithBlock:(NSString *(^)(GRMustacheSection* section))block AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 @end
 

include/GRMustacheInvocation.h

@@ -23,11 +23,59 @@
 #import <Foundation/Foundation.h>
 #import "GRMustacheAvailabilityMacros.h"
 
+/**
+ * The GRMustacheInvocation class gives you information about the values that
+ * are found in the context stack when rendering tags such as `{{name}}`.
+ *
+ * You'll be given GRMustacheInvocation instances when providing a
+ * GRMustacheTemplateDelegate to your templates.
+ *
+ * **Companion guide:** https://github.com/groue/GRMustache/blob/master/Guides/delegate.md
+ * 
+ * @see GRMustacheTemplateDelegate
+ *
+ * @since v1.12
+ */
 @interface GRMustacheInvocation : NSObject {
 @private
     id _returnValue;
     id _token;
 }
+
+/**
+ * The key that did provide the return value of the invocation.
+ *
+ * For instance, the invocation that you would get for a `{{name}}` tag would
+ * have @"name" in its `key` property, and the name in the `returnValue`
+ * property.
+ *
+ * For tags with compound keys, such as `{{person.name}}`, the key will be
+ * @"name" if the person could be found in the context stack. It would be
+ * @"person" otherwise.
+ *
+ * @see returnValue
+ *
+ * @since v1.12
+ */
 @property (nonatomic, readonly) NSString *key AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ * The return value of the invocation.
+ *
+ * For instance, the invocation that you would get for a `{{name}}` tag would
+ * have the name in the `returnValue` property.
+ *
+ * For tags with compound keys, such as `{{person.name}}`, the value will be
+ * the person's name, if the person could be found in the context stack.
+ * It would be nil otherwise.
+ *
+ * In a template's delegate methods, you can set the returnValue of an
+ * invocation, and alter a template rendering.
+ *
+ * @see key
+ * @see GRMustacheTemplateDelegate
+ *
+ * @since v1.12
+ */
 @property (nonatomic, retain) id returnValue AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 @end

include/GRMustacheSection.h

@@ -27,7 +27,18 @@
 @class GRMustacheTemplate;
 
 /**
- A GRMustacheSection represents a Mustache section such as `{{#name}}...{{/name}}`.
+ * A GRMustacheSection represents a Mustache section such as 
+ * `{{#name}}...{{/name}}`.
+ *
+ * You will be provided with GRMustacheSection objects when implementing
+ * mustache lambda sections with objects conforming to the GRMustacheHelper
+ * protocol.
+ *
+ * **Companion guide:** https://github.com/groue/GRMustache/blob/master/Guides/runtime/helpers.md
+ *
+ * @see GRMustacheHelper
+ *
+ * @since v1.3
  */
 @interface GRMustacheSection: NSObject {
 @private
@@ -46,7 +57,9 @@
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- Returns the current rendering context.
+ * The current rendering context.
+ *
+ * @since v2.0
  */
 @property (nonatomic, readonly) id renderingContext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 
@@ -58,7 +71,10 @@
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- Returns the literal inner content of the section, with unprocessed mustache `{{tags}}`.
+ * The literal inner content of the section, with unprocessed Mustache
+ * `{{tags}}`.
+ *
+ * @since v2.0
  */
 @property (nonatomic, readonly) NSString *innerTemplateString AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
 
@@ -68,9 +84,11 @@
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- Renders the inner content of the receiver with the current context
- 
- @return A string containing the rendered inner content.
+ * Renders the inner content of the receiver with the current context
+ * 
+ * @return A string containing the rendered inner content.
+ *
+ * @since v2.0
  */
 - (NSString *)render AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;