Add code documentation.

@throws breaks Xcode quick help, so exceptions info is added to Discussion

CleverTapSDK/InApps/CustomTemplates/CTAppFunctionBuilder.h

@@ -11,8 +11,19 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ Builder for ``CTCustomTemplate`` functions. See ``CTCustomTemplateBuilder``.
+ */
 @interface CTAppFunctionBuilder : CTCustomTemplateBuilder
 
+/*!
+ Use `isVisual` to set if the template has UI or not. 
+ If set to `YES` the template is registered as part of the in-apps queue
+ and must be explicitly dismissed before other in-apps can be shown.
+ If set to `NO` the template is executed directly and does not require dismissal nor it impedes other in-apps.
+ 
+ @param isVisual Whether the function will present UI.
+ */
 - (instancetype)initWithIsVisual:(BOOL)isVisual;
 
 @end

CleverTapSDK/InApps/CustomTemplates/CTCustomTemplate.h

@@ -10,9 +10,20 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ A definition of a custom template. Can be a function or a code template.
+ Instances are uniquely identified by their name.
+ */
 @interface CTCustomTemplate : NSObject
 
+/*!
+ The name of the template.
+ */
 @property (nonatomic, strong, readonly) NSString *name;
+
+/*!
+ Whether the template has UI or not.
+ */
 @property (nonatomic, readonly) BOOL isVisual;
 
 - (instancetype)init NS_UNAVAILABLE;

CleverTapSDK/InApps/CustomTemplates/CTCustomTemplateBuilder.h

@@ -15,10 +15,42 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ Builder for ``CTCustomTemplate``s creation. Set `name` and  `presenter` before calling ``build``.
+ Arguments can be specified by using one of the `addArgument:` methods. Argument names must be unique.
+ The "." characters in template arguments' names denote hierarchical structure. 
+ They are treated the same way as the keys within dictionaries passed to ``addArgument:withDictionary:``.
+ If a higher-level name (to the left of a "." symbol) matches a dictionary argument's name,
+ it is treated the same as if the argument was part of the dictionary itself.
+ 
+ For example, the following code snippets define identical arguments:
+ ```
+ [builder addArgument:@"map" withDictionary:@{
+    @"a": @5,
+    @"b": @6
+ }];
+ ```
+ and
+ ```
+ [builder addArgument:@"map.a" withNumber:@5];
+ [builder addArgument:@"map.b" withNumber:@6];
+ ```
+ 
+ Methods of this class throw `NSException`  with name `CleverTapCustomTemplateException`
+ for invalid states or parameters. Defined templates must be correct when the app is running. If such an
+ exception is thrown the template definition must be corrected instead of handling the error.
+ */
 @interface CTCustomTemplateBuilder : NSObject
 
 - (instancetype)init NS_UNAVAILABLE;
 
+/*!
+ The name for the template. It should be provided exactly once. 
+ It must be unique across template definitions.
+ Must be non-blank.
+ 
+ This method throws `NSException`  with name `CleverTapCustomTemplateException` if the name is already set or the provided name is blank.
+ */
 - (void)setName:(NSString *)name;
 
 - (void)addArgument:(NSString *)name withString:(NSString *)defaultValue
@@ -30,13 +62,29 @@ NS_SWIFT_NAME(addArgument(_:number:));
 - (void)addArgument:(NSString *)name withBool:(BOOL)defaultValue
 NS_SWIFT_NAME(addArgument(_:boolean:));
 
+/*!
+ Add a dictionary structure to the arguments of the ``CTCustomTemplate``. 
+ The `name` should be unique across all arguments and also
+ all keys in `defaultValue` should form unique names across all arguments.
+ 
+ @param defaultValue The dictionary must be non-empty. Values can be of type `NSNumber` or `NSString` or another `NSDictionary` which values can also be of the same types.
+ */
 - (void)addArgument:(nonnull NSString *)name withDictionary:(nonnull NSDictionary *)defaultValue
 NS_SWIFT_NAME(addArgument(_:dictionary:));
 
 - (void)addFileArgument:(NSString *)name;
 
+/*!
+ The presenter for this template. See ``CTTemplatePresenter``.
+ */
 - (void)setPresenter:(id<CTTemplatePresenter>)presenter;
 
+/*!
+ Creates the ``CTCustomTemplate`` with the previously defined name, arguments and presenter.
+ Name and presenter must be set before calling this method.
+ 
+ This method throws `NSException`  with name `CleverTapCustomTemplateException` if name or presenter were not set.
+ */
 - (CTCustomTemplate *)build;
 
 @end

CleverTapSDK/InApps/CustomTemplates/CTInAppTemplateBuilder.h

@@ -11,10 +11,18 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ Builder for ``CTCustomTemplate`` code templates. See ``CTCustomTemplateBuilder``.
+ */
 @interface CTInAppTemplateBuilder : CTCustomTemplateBuilder
 
 - (instancetype)init;
 
+/*!
+ Action arguments are specified by name only. When the ``CTCustomTemplate`` is triggered, the configured action
+ can be executed through ``CTTemplateContext/triggerActionNamed:``.
+ Action values could either be a predefined action (like close or open-url) or а registered ``CTCustomTemplate`` function.
+ */
 - (void)addActionArgument:(NSString *)name;
 
 @end

CleverTapSDK/InApps/CustomTemplates/CTJsonTemplateProducer.h

@@ -14,14 +14,78 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ A ``CTTemplateProducer`` that creates templates based on a json definition.
+ */
 @interface CTJsonTemplateProducer : NSObject <CTTemplateProducer>
 
 - (instancetype)init NS_UNAVAILABLE;
 
+/*!
+ Creates a template producer with a json definition, template presenter and function presenter.
+ 
+ See ``CTTemplatePresenter`` for more information on the template/function presenter.
+ 
+ Invalid definitions throw `NSException` with name `CleverTapCustomTemplateException` when ``defineTemplates:`` is called.
+ 
+ @param jsonTemplateDefinitions A string with a json definition of templates in the following format:
+ ```
+ {
+   "TemplateName": {
+     "type": "template",
+     "arguments": {
+       "Argument1": {
+         "type": "string|number|boolean|file|action|object",
+         "value": "val" // different type depending on "type", e.g 12.5, true, "str" or {}
+         },
+       "Argument2": {
+         "type": "object",
+         "value": {
+           "Nested1": {
+             "type": "string|number|boolean|object", // file and action cannot be nested
+             "value": {}
+           },
+           "Nested2": {
+             "type": "string|number|boolean|object",
+             "value": "val"
+           }
+         }
+       }
+     }
+   },
+   "functionName": {
+     "type": "function",
+     "isVisual": true|false,
+     "arguments": {
+       "a": {
+       "type": "string|number|boolean|file|object", // action arguments are not supported for functions
+       "value": "val"
+       }
+     }
+   }
+ }
+ ```
+ 
+ @param templatePresenter A presenter for all templates in the json definitions. Required if there
+        is at least one template with type "template".
+ 
+ @param functionPresenter A presenter for all functions in the json definitions. Required if there
+        is at least one template with type "function".
+ */
 - (nonnull instancetype)initWithJsonTemplateDefinitions:(nonnull NSString *)jsonTemplateDefinitions
                                       templatePresenter:(nonnull id<CTTemplatePresenter>)templatePresenter
                                       functionPresenter:(nonnull id<CTTemplatePresenter>)functionPresenter;
 
+
+/*!
+ Creates ``CTCustomTemplate``s based on the `jsonTemplateDefinitions` this ``CTJsonTemplateProducer`` was initialized with.
+ 
+ @param instanceConfig The config of the CleverTap instance.
+ @return A set of the custom templates created.
+ 
+ This method throws an `NSException` with name `CleverTapCustomTemplateException` if an invalid JSON format or values occur while parsing `jsonTemplateDefinitions`.
+ See the exception reason for details.
+ */
 - (NSSet<CTCustomTemplate *> * _Nonnull)defineTemplates:(CleverTapInstanceConfig * _Nonnull)instanceConfig;
 
 @end

CleverTapSDK/InApps/CustomTemplates/CTTemplateContext.h

@@ -10,60 +10,129 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ Representation of the context around a ``CTCustomTemplate``. Use the `<type>Named:` methods to obtain the
+ current values of the arguments. Use ``triggerActionNamed:`` to trigger template actions.
+ Use ``presented`` and ``dismissed`` to notify the SDK of the current state of this InApp context.
+ */
 @interface CTTemplateContext : NSObject
 
 - (instancetype)init NS_UNAVAILABLE;
 
+/*!
+ The name of the template or function.
+ 
+ @return The name of the ``CTCustomTemplate``.
+ */
 - (NSString *)templateName
 NS_SWIFT_NAME(name());
 
+/*!
+ Retrieve a `NSString` argument by `name`.
+ 
+ @return The argument value or `nil` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (nullable NSString *)stringNamed:(NSString *)name
 NS_SWIFT_NAME(string(name:));
 
+/*!
+ Retrieve a `NSNumber` argument by `name`.
+ 
+ @return The argument value or `nil` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (nullable NSNumber *)numberNamed:(NSString *)name
 NS_SWIFT_NAME(number(name:));
 
+/*!
+ Retrieve a `char` argument by `name`.
+ 
+ @return The argument value or `0` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (int)charNamed:(NSString *)name
 NS_SWIFT_NAME(char(name:));
 
+/*!
+ Retrieve an `int` argument by `name`.
+ 
+ @return The argument value or `0` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (int)intNamed:(NSString *)name
 NS_SWIFT_NAME(int(name:));
 
+/*!
+ Retrieve a `double` argument by `name`.
+ 
+ @return The argument value or `0` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (double)doubleNamed:(NSString *)name
 NS_SWIFT_NAME(double(name:));
 
+/*!
+ Retrieve a `float` argument by `name`.
+ 
+ @return The argument value or `0` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (float)floatNamed:(NSString *)name
 NS_SWIFT_NAME(float(name:));
 
+/*!
+ Retrieve a `long` argument by `name`.
+ 
+ @return The argument value or `0` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (long)longNamed:(NSString *)name
 NS_SWIFT_NAME(long(name:));
 
+/*!
+ Retrieve a `long long` argument by `name`.
+ 
+ @return The argument value or `0` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (long long)longLongNamed:(NSString *)name
 NS_SWIFT_NAME(longLong(name:));
 
+/*!
+ Retrieve a `BOOL` argument by `name`.
+ 
+ @return The argument value or `NO` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (BOOL)boolNamed:(NSString *)name
 NS_SWIFT_NAME(boolean(name:));
 
+/*!
+ Retrieve a dictionary of all arguments under `name`. Dictionary arguments will be combined with dot notation arguments. All
+ values are converted to their defined type in the ``CTCustomTemplate``. Action arguments are mapped to their
+ name as `NSString`. Returns `nil` if no arguments are found for the requested map.
+ 
+ @return A dictionary of all arguments under `name` or `nil`.
+ */
 - (nullable NSDictionary *)dictionaryNamed:(NSString *)name
 NS_SWIFT_NAME(dictionary(name:));
 
+/*!
+ Retrieve an absolute file path argument by `name`.
+ 
+ @return The argument value or `nil` if no such argument is defined for the ``CTCustomTemplate``.
+ */
 - (nullable NSString *)fileNamed:(NSString *)name
 NS_SWIFT_NAME(file(name:));
 
-/**
- * Call this method to notify the SDK the template is presented.
+/*!
+ Call this method to notify the SDK the ``CTCustomTemplate`` is presented.
  */
 - (void)presented;
 
-/**
- * Executes the action given by the "name" key.
- * Records Notification Clicked event.
+/*!
+ Trigger an action argument by `name`.
+ Records a "Notification Clicked" event.
  */
 - (void)triggerActionNamed:(NSString *)name
 NS_SWIFT_NAME(triggerAction(name:));
 
-/**
- * Call this method to notify the SDK the template is dismissed.
+/*!
+ Notify the SDK that the current ``CTCustomTemplate`` is dismissed. The current ``CTCustomTemplate`` is considered to be
+ visible to the user until this method is called. Since the SDK can show only one InApp message at a time, all
+ other messages will be queued until the current one is dismissed.
  */
 - (void)dismissed;
 

CleverTapSDK/InApps/CustomTemplates/CTTemplatePresenter.h

@@ -13,11 +13,26 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/*!
+ A handler of custom code templates ``CTCustomTemplate``. Its methods are called when the corresponding InApp
+ message should be presented to the user or closed.
+ */
 @protocol CTTemplatePresenter
 
+/*!
+ Called when a ``CTCustomTemplate`` should be presented or a function should be executed. For visual templates
+ (code templates and functions with ``CTCustomTemplate/isVisual`` equals `YES`)  implementing classes should use the provided
+ ``CTTemplateContext`` methods ``CTTemplateContext/presented`` and
+ ``CTTemplateContext/dismissed`` to notify the SDK of the state of the template invocation. Only
+ one visual template or other InApp message can be displayed at a time by the SDK and no new messages can be
+ shown until the current one is dismissed.
+ */
 - (void)onPresent:(CTTemplateContext *)context
 NS_SWIFT_NAME(onPresent(context:));
 
+/*!
+ Called when a ``CTCustomTemplate`` action Notification Close is executed. Dismiss the custom template InApp and call ``CTTemplateContext/dismissed`` to notify the SDK the template is dismissed.
+ */
 - (void)onCloseClicked:(CTTemplateContext *)context
 NS_SWIFT_NAME(onCloseClicked(context:));
 

CleverTapSDK/InApps/CustomTemplates/CTTemplateProducer.h

@@ -14,6 +14,13 @@
 
 @protocol CTTemplateProducer
 
+/*!
+ Defines custom templates.
+ 
+ @param instanceConfig Use the config to decide which instance the templates are defined for.
+ 
+ @return A set of ``CTCustomTemplate`` definitions. ``CTCustomTemplate``s are uniquely identified by their name.
+ */
 - (NSSet<CTCustomTemplate *> * _Nonnull)defineTemplates:(CleverTapInstanceConfig * _Nonnull)instanceConfig;
 
 @end