Add Jazzy support for the offline mode

Author: Clément Le Provost

.gitignore

@@ -16,3 +16,8 @@ DerivedData
 *.hmap
 *.ipa
 *.xcuserstate
+
+# Cocoapods
+/*.xcworkspace
+/Pods
+

AlgoliaSearch.xcodeproj/project.pbxproj

@@ -0,0 +1,7 @@
+# NOTE: This Podfile is used to draw dependencies when building the project independently (e.g. for unit tests).
+
+use_frameworks!
+
+target "AlgoliaSearch-Offline-iOS" do
+    pod 'AlgoliaSearchOfflineCore-iOS', '~> 0.2'
+end

Podfile

@@ -0,0 +1,12 @@
+PODS:
+  - AlgoliaSearchOfflineCore-iOS (0.2)
+
+DEPENDENCIES:
+  - AlgoliaSearchOfflineCore-iOS (~> 0.2)
+
+SPEC CHECKSUMS:
+  AlgoliaSearchOfflineCore-iOS: 5cfeb295c4e8412182cc7450b0487806901472ec
+
+PODFILE CHECKSUM: 70f8e7e3ce3a1a02df550109e528d546a9555548
+
+COCOAPODS: 1.0.1

Podfile.lock

@@ -25,11 +25,16 @@ import AlgoliaSearchOfflineCore
 import Foundation
 
 
-/// A data selection query.
+/// A data selection query, used to select data to be mirrored locally by a `MirroredIndex`.
+///
 @objc public class DataSelectionQuery: NSObject {
+    /// Query used to select data.
     @objc public let query: Query
-    @objc public let maxObjects: Int
 
+    /// Maximum number of objects to retrieve with this query.
+    @objc public let maxObjects: Int
+
+    /// Create a new data selection query.
     @objc public init(query: Query, maxObjects: Int) {
         self.query = query
         self.maxObjects = maxObjects
@@ -46,19 +51,19 @@ import Foundation
 
 /// An online index that can also be mirrored locally.
 ///
-/// When created, an instance of this class has its <code>mirrored</code> flag set to false, and behaves like a normal,
+/// When created, an instance of this class has its `mirrored` flag set to false, and behaves like a normal,
 /// online `Index`. When the `mirrored` flag is set to true, the index becomes capable of acting upon local data.
 ///
-/// It is a programming error to call methods acting on the local data when `mirrored` is false. Doing so
+/// + Warning: It is a programming error to call methods acting on the local data when `mirrored` is false. Doing so
 /// will result in an assertion error being raised.
 ///
 /// Native resources are lazily instantiated at the first method call requiring them. They are released when the
 /// object is released. Although the client guards against concurrent accesses, it is strongly discouraged
 /// to create more than one `MirroredIndex` instance pointing to the same index, as that would duplicate
 /// native resources.
 ///
-/// NOTE: Requires Algolia's SDK. The `OfflineClient.enableOfflineMode()` method must be called with a valid license
-/// key prior to calling any offline-related method.
+/// + Note: Requires Algolia's SDK. The `OfflineClient.enableOfflineMode(...)` method must be called with a valid
+/// license key prior to calling any offline-related method.
 ///
 /// ### Request strategy
 ///
@@ -68,10 +73,10 @@ import Foundation
 /// `FallbackOnFailure`, which will always target the online API first, then fallback to the offline mirror in case of
 /// failure (including network unavailability).
 ///
-/// NOTE: If you want to explicitly target either the online API or the offline mirror, doing so is always possible
-/// using the `searchOnline()` or `searchOffline()` methods.
+/// + Note: If you want to explicitly target either the online API or the offline mirror, doing so is always possible
+/// using the `searchOnline(...)` or `searchOffline(...)` methods.
 ///
-/// NOTE: The strategy applies both to `search()` and `searchDisjunctiveFaceting()`.
+/// + Note: The strategy applies both to `search(...)` and `searchDisjunctiveFaceting(...)`.
 ///
 @objc public class MirroredIndex : Index {
 
@@ -102,9 +107,9 @@ import Foundation
     // MARK: Properties
     // ----------------------------------------------------------------------
 
-    /// Getter returning covariant-typed client.
-    // IMPLEMENTATION NOTE: Could not find a way to implement proper covariant properties in Swift.
+    /// The offline client used by this index.
     @objc public var offlineClient: OfflineClient {
+        // IMPLEMENTATION NOTE: Could not find a way to implement proper covariant properties in Swift.
         return self.client as! OfflineClient
     }
 
@@ -157,7 +162,7 @@ import Foundation
     // MARK: - Init
     // ----------------------------------------------------------------------
 
-    @objc public override init(client: Client, indexName: String) {
+    @objc override internal init(client: Client, indexName: String) {
         assert(client is OfflineClient);
         super.init(client: client, indexName: indexName)
     }
@@ -167,7 +172,9 @@ import Foundation
     // ----------------------------------------------------------------------
 
     /// Syncing indicator.
-    /// NOTE: To prevent concurrent access to this variable, we always access it from the build (serial) queue.
+    ///
+    /// + Note: To prevent concurrent access to this variable, we always access it from the build (serial) queue.
+    ///
     private var syncing: Bool = false
 
     /// Path to the temporary directory for the current sync.
@@ -203,7 +210,9 @@ import Foundation
 
     /// Add a data selection query to the local mirror.
     /// The query is not run immediately. It will be run during the subsequent refreshes.
-    /// @pre The index must have been marked as mirrored.
+    ///
+    /// + Precondition: Mirroring must have been activated on this index (see the `mirrored` property).
+    ///
     @objc public func addDataSelectionQuery(query: DataSelectionQuery) {
         assert(mirrored);
         mirrorSettings.queries.append(query)
@@ -213,7 +222,9 @@ import Foundation
 
     /// Add any number of data selection queries to the local mirror.
     /// The query is not run immediately. It will be run during the subsequent refreshes.
-    /// @pre The index must have been marked as mirrored.
+    ///
+    /// + Precondition: Mirroring must have been activated on this index (see the `mirrored` property).
+    ///
     @objc public func addDataSelectionQueries(queries: [DataSelectionQuery]) {
         assert(mirrored);
         mirrorSettings.queries.appendContentsOf(queries)
@@ -224,6 +235,8 @@ import Foundation
     /// Launch a sync.
     /// This unconditionally launches a sync, unless one is already running.
     ///
+    /// + Precondition: Mirroring must have been activated on this index (see the `mirrored` property).
+    ///
     @objc public func sync() {
         assert(self.mirrored, "Mirroring not activated on this index")
         offlineClient.buildQueue.addOperationWithBlock() {
@@ -234,6 +247,8 @@ import Foundation
     /// Launch a sync if needed.
     /// This takes into account the delay between syncs.
     ///
+    /// + Precondition: Mirroring must have been activated on this index (see the `mirrored` property).
+    ///
     @objc public func syncIfNeeded() {
         assert(self.mirrored, "Mirroring not activated on this index")
         if self.isSyncDelayExpired() || self.isMirrorSettingsDirty() {
@@ -431,7 +446,7 @@ import Foundation
         /// Search online only.
         /// The search will fail when the API can't be reached.
         ///
-        /// NOTE: You might consider that this defeats the purpose of having a mirror in the first place... But this
+        /// + Note: You might consider that this defeats the purpose of having a mirror in the first place... But this
         /// is intended for applications wanting to manually manage their policy.
         ///
         case OnlineOnly = 0
@@ -460,7 +475,7 @@ import Foundation
 
     /// Timeout used to control offline fallback.
     ///
-    /// NOTE: Only used by the `FallbackOnTimeout` strategy.
+    /// + Note: Only used by the `FallbackOnTimeout` strategy.
     ///
     @objc public var offlineFallbackTimeout: NSTimeInterval = 1.0
 
@@ -815,7 +830,7 @@ import Foundation
     // fall back could only work for the first query.
 
     /// Browse the local mirror (initial call).
-    /// Same semantics as `Index.browse()`.
+    /// Same semantics as `Index.browse(...)`.
     ///
     @objc public func browseMirror(query: Query, completionHandler: CompletionHandler) -> NSOperation {
         assert(self.mirrored, "Mirroring not activated on this index")
@@ -835,7 +850,7 @@ import Foundation
     }
 
     /// Browse the index from a cursor.
-    /// Same semantics as `Index.browseFrom()`.
+    /// Same semantics as `Index.browseFrom(...)`.
     ///
     @objc public func browseMirrorFrom(cursor: String, completionHandler: CompletionHandler) -> NSOperation {
         assert(self.mirrored, "Mirroring not activated on this index")

Source/Offline/MirroredIndex.swift

@@ -27,14 +27,17 @@ import Foundation
 
 /// An API client that adds offline features on top of the regular online API client.
 ///
-/// NOTE: Requires Algolia's SDK. The `enableOfflineMode()` method must be called with a valid license key prior to
-/// calling any offline-related method.
-//
+/// + Note: Requires Algolia's Offline Core SDK. The `enableOfflineMode(...)` method must be called with a valid license
+/// key prior to calling any offline-related method.
+///
 @objc public class OfflineClient : Client {
-    /// Algolia Search initialization.
+    /// Create a new offline-capable Algolia Search client.
+    ///
+    /// + Note: Offline mode is disabled by default, until you call `enableOfflineMode(...)`.
     ///
     /// - parameter appID: the application ID you have in your admin interface
     /// - parameter apiKey: a valid API key for the service
+    ///
     @objc public override init(appID: String, apiKey: String) {
         buildQueue.name = "AlgoliaSearch-Build"
         buildQueue.maxConcurrentOperationCount = 1
@@ -49,9 +52,9 @@ import Foundation
 
     /// Path to directory where the local data is stored.
     /// Defaults to an `algolia` sub-directory inside the `Library/Application Support` directory.
-    /// If you set it to another value, do so *before* calling `enableOfflineMode()`.
+    /// If you set it to another value, do so *before* calling `enableOfflineMode(...)`.
     ///
-    /// WARNING: This directory will be explicitly excluded from iCloud/iTunes backup.
+    /// + Warning: This directory will be explicitly excluded from iCloud/iTunes backup.
     ///
     @objc public var rootDataDir: String
 
@@ -92,7 +95,9 @@ import Foundation
     }
 
     /// Create a new index.
-    /// NOTE: The offline client returns mirror-capable indices.
+    ///
+    /// + Note: The offline client returns mirror-capable indices.
+    ///
     @objc public override func getIndex(indexName: String) -> MirroredIndex {
         return MirroredIndex(client: self, indexName: indexName)
     }

Source/Offline/OfflineClient.swift

@@ -79,8 +79,15 @@ keep versioning aligned (there is only one version number for both flavors).
 
 Documentation is generated by [Jazzy](https://github.com/realm/jazzy). Of course you will need to install it first: `sudo gem install jazzy` should do the trick.
 
-Generating the documentation is as simple as running:
+For the online mode, generating the documentation is as simple as running:
 
 ```
 jazzy --clean
 ```
+
+For the offline mode, it is a little more complicated. We use Cocoapods to draw the dependencies. The Cocoapods-generated workspace is then used to build the documentation:
+
+```
+pod update
+jazzy --config offline.jazzy.yaml --clean
+```

doc/maintenance.md

@@ -0,0 +1,15 @@
+# In the case of the offline flavor, the Xcode project is not standalone: we need the Cocoapods-generated workspace
+# to draw dependencies.
+xcodebuild_arguments:
+    - -workspace
+    - AlgoliaSearch.xcworkspace
+    - -scheme
+    - AlgoliaSearch-Offline-iOS
+documentation:
+    - doc/offline-mode.md
+output: build/doc
+# Avoid putting the DocSet within the HTML docs.
+# WARNING: The path is relative to the output directory.
+docset_path: ../docset
+hide_documentation_coverage: true
+skip_undocumented: true