2424import Foundation
2525
2626
27+ /// Signature of most completion handlers used by this library.
28+ ///
29+ /// - parameter content: The JSON response (in case of success) or `nil` (in case of error).
30+ /// - parameter error: The encountered error (in case of error) or `nil` (in case of success).
31+ ///
32+ /// + Note: `content` and `error` are mutually exclusive: only one will be non-nil.
33+ ///
34+ public typealias CompletionHandler = ( content: [ String : AnyObject ] ? , error: NSError ? ) -> Void
35+
36+
2737/// A version of a software library.
2838/// Used to construct the `User-Agent` header.
2939///
3040@objc public class LibraryVersion : NSObject {
41+ /// Library name.
3142 @objc public let name : String
43+
44+ /// Version string.
3245 @objc public let version : String
3346
3447 @objc public init ( name: String , version: String ) {
@@ -46,22 +59,23 @@ public func ==(lhs: LibraryVersion, rhs: LibraryVersion) -> Bool {
4659public let ErrorDomain = " AlgoliaSearch "
4760
4861
49- /// Entry point in the Swift API.
62+ /// Entry point into the Swift API.
5063///
51- /// You should instantiate a Client object with your AppID, ApiKey and Hosts
52- /// to start using Algolia Search API.
5364@objc public class Client : NSObject {
5465 // MARK: Constants
5566
5667 /// Error domain used for errors raised by this module.
57- /// + NOTE: This shortcut is provided for Objective-C bridging. See the top-level `ErrorDomain` constant.
68+ ///
69+ /// + Note: This shortcut is provided for Objective-C bridging. See the top-level `ErrorDomain` constant.
70+ ///
5871 @objc public static let ErrorDomain = AlgoliaSearch . ErrorDomain
5972
6073 // MARK: Properties
6174
6275 /// HTTP headers that will be sent with every request.
6376 @objc public var headers = [ String: String] ( )
64-
77+
78+ /// Algolia API key.
6579 @objc public var apiKey : String {
6680 didSet {
6781 updateHeadersFromAPIKey ( )
@@ -74,7 +88,7 @@ public let ErrorDomain = "AlgoliaSearch"
7488 /// The list of libraries used by this client, passed in the `User-Agent` HTTP header of every request.
7589 /// It is initially set to contain only this API Client, but may be overridden to include other libraries.
7690 ///
77- /// * WARNING: The user agent is crucial to proper statistics in your Algolia dashboard. Please leave it as is.
91+ /// + WARNING: The user agent is crucial to proper statistics in your Algolia dashboard. Please leave it as is.
7892 /// This field is publicly exposed only for the sake of other Algolia libraries.
7993 ///
8094 @objc public var userAgents : [ LibraryVersion ] = [ ] {
@@ -86,18 +100,19 @@ public let ErrorDomain = "AlgoliaSearch"
86100 headers [ " User-Agent " ] = userAgents. map ( { return " \( $0. name) ( \( $0. version) ) " } ) . joinWithSeparator ( " ; " )
87101 }
88102
89- /// Default timeout for network requests. Default: 30" .
103+ /// Default timeout for network requests. Default: 30 seconds .
90104 @objc public let timeout : NSTimeInterval = 30
91105
92- /// Timeout for search requests. Default: 5" .
106+ /// Timeout for search requests. Default: 5 seconds .
93107 @objc public let searchTimeout : NSTimeInterval = 5
94108
109+ /// Algolia application ID.
95110 @objc public let appID : String
96111
97112 /// Hosts for read queries, in priority order.
98113 /// The first host will always be used, then subsequent hosts in case of retry.
99114 ///
100- /// WARNING : The default values should be appropriate for most use cases.
115+ /// + Warning : The default values should be appropriate for most use cases.
101116 /// Change them only if you know what you are doing.
102117 ///
103118 @objc public var readHosts : [ String ] {
@@ -109,7 +124,7 @@ public let ErrorDomain = "AlgoliaSearch"
109124 /// Hosts for write queries, in priority order.
110125 /// The first host will always be used, then subsequent hosts in case of retry.
111126 ///
112- /// WARNING : The default values should be appropriate for most use cases.
127+ /// + Warning : The default values should be appropriate for most use cases.
113128 /// Change them only if you know what you are doing.
114129 ///
115130 @objc public var writeHosts : [ String ] {
@@ -118,15 +133,11 @@ public let ErrorDomain = "AlgoliaSearch"
118133 }
119134 }
120135
121- /// Set read and write hosts to the same value (convenience method).
122- @objc public func setHosts( hosts: [ String ] ) {
123- readHosts = hosts
124- writeHosts = hosts
125- }
126-
127136 // NOTE: Not constant only for the sake of mocking during unit tests.
128137 var session : URLSession
129138
139+ // MARK: Initialization
140+
130141 /// Create a new Algolia Search client.
131142 ///
132143 /// - parameter appID: The application ID (available in your Algolia Dashboard).
@@ -170,23 +181,33 @@ public let ErrorDomain = "AlgoliaSearch"
170181 updateHeadersFromUserAgents ( )
171182 }
172183
184+ /// Set read and write hosts to the same value (convenience method).
185+ ///
186+ /// + Warning: The default values should be appropriate for most use cases.
187+ /// Change them only if you know what you are doing.
188+ ///
189+ @objc public func setHosts( hosts: [ String ] ) {
190+ readHosts = hosts
191+ writeHosts = hosts
192+ }
193+
173194 /// Set an HTTP header that will be sent with every request.
174195 ///
175- /// NOTE : You may also use the `headers` property directly.
196+ /// + Note : You may also use the `headers` property directly.
176197 ///
177198 /// - parameter name: Header name.
178- /// - parameter value: Value for the header. If nil, the header will be removed.
199+ /// - parameter value: Value for the header. If ` nil` , the header will be removed.
179200 ///
180- @objc public func setHeader( name: String ! , value: String ) {
201+ @objc public func setHeader( name: String , value: String ? ) {
181202 headers [ name] = value
182203 }
183204
184205 /// Get an HTTP header.
185206 ///
186- /// NOTE : You may also use the `headers` property directly.
207+ /// + Note : You may also use the `headers` property directly.
187208 ///
188209 /// - parameter name: Header name.
189- /// - returns: The header's value, or nil if the header does not exist.
210+ /// - returns: The header's value, or ` nil` if the header does not exist.
190211 ///
191212 @objc public func getHeader( name: String ) -> String ? {
192213 return headers [ name]
@@ -266,7 +287,7 @@ public let ErrorDomain = "AlgoliaSearch"
266287 return Index ( client: self , indexName: indexName)
267288 }
268289
269- /// Strategy when running multiple queries. See `Client.multipleQueries()`.
290+ /// Strategy when running multiple queries. See `Client.multipleQueries(... )`.
270291 ///
271292 public enum MultipleQueriesStrategy : String {
272293 /// Execute the sequence of queries until the end.
0 commit comments