Permalink
Browse files

v4.1.1

  • Loading branch information...
1 parent e6c2079 commit 0d322bc9635600872528d7f44d5d4362ec1a5ce5 @groue committed Jul 1, 2012
View
@@ -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>
View
@@ -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;
View
@@ -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;
View
@@ -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
@@ -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
@@ -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;
Oops, something went wrong.

0 comments on commit 0d322bc

Please sign in to comment.