Inline docs and generated docs (#41)

Closes #8 * Account docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Cafes docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Comments docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Contacts docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Feed docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Files docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Flags docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Ignores docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Invites docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Adds docs build; can server folder with gh pages Signed-off-by: andrew <andrewxhill@gmail.com> * ignore docs folder Signed-off-by: andrew <andrewxhill@gmail.com> * deleted Signed-off-by: andrew <andrewxhill@gmail.com> * just checking docs in Signed-off-by: andrew <andrewxhill@gmail.com> * IPFS docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Likes docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Logs docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Messages docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Notifications docs Signed-off-by: Aaron Sutula <hi@asutula.com> * clean up index Signed-off-by: andrew <andrew@textile.io> * Profile docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Schemas docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Updating class docs for consistency Signed-off-by: Aaron Sutula <hi@asutula.com> * Textile docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Threads docs Signed-off-by: Aaron Sutula <hi@asutula.com> * TextileDelegate docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Don't run pod update in setup Signed-off-by: Aaron Sutula <hi@asutula.com> * Exclude internal base class Signed-off-by: Aaron Sutula <hi@asutula.com> * Generate complete docs Signed-off-by: Aaron Sutula <hi@asutula.com> * Update return types for bock hashes Signed-off-by: Aaron Sutula <hi@asutula.com>
textileio · May 24, 2019 · 8934ccc · 8934ccc
1 parent 36654ba
commit 8934ccc
Show file tree

Hide file tree

Showing 91 changed files with 21,393 additions and 9 deletions.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,14 @@
+setup:
+	gem install jazzy
+	(cd Example; pod install)
+
+build_docs:
+	jazzy \
+  --objc \
+  --author Textile \
+  --author_url https://textile.io \
+  --github_url https://github.com/textileio/ios-textile \
+  --umbrella-header Textile/classes/TextileApi.h \
+  --framework-root . \
+  --module Textile \
+  --exclude=/*/NodeDependant*
diff --git a/README.md b/README.md
@@ -5,13 +5,17 @@
 [![License](https://img.shields.io/cocoapods/l/Textile.svg?style=flat)](https://cocoapods.org/pods/Textile)
 [![Platform](https://img.shields.io/cocoapods/p/Textile.svg?style=flat)](https://cocoapods.org/pods/Textile)
 
-## Example
+Textile provides encrypted, recoverable, schema-based, and cross-application data storage built on IPFS and libp2p. We like to think of it as a decentralized data wallet with built-in protocols for sharing and recovery, or more simply, an open and programmable iCloud.
 
-To run the example project, clone the repo, and run `pod install` from the Example directory first.
+To learn more, please head over to the [Textile documentation](https://docs.textile.io/).
+
+## Getting Started
+
+[Click here to read the iOS getting started guide](https://docs.textile.io/develop/clients/ios/).
 
 ## Requirements
 
-## Installation
+### Installation
 
 Textile is available through [CocoaPods](https://cocoapods.org). To install
 it, simply add the following line to your Podfile:
@@ -20,6 +24,10 @@ it, simply add the following line to your Podfile:
 pod 'Textile'
 ```
 
+## Example
+
+To run the example project, clone the repo, and run `pod install` from the Example directory first.
+
 ## Author
 
 Textile, contact@textile.io

diff --git a/Textile/Classes/AccountApi.h b/Textile/Classes/AccountApi.h
@@ -12,13 +12,49 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile account related APIs
+ */
 @interface AccountApi : NodeDependant
 
+/**
+ * @return The address of the Textile account
+ */
 - (NSString *)address;
+
+/**
+ * @return The seed of the Textile account
+ */
 - (NSString *)seed;
+
+/**
+ * Encrypt raw data with the account private key
+ * @param data The data to encrypt
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The encryped data
+ */
 - (nullable NSData *)encrypt:(NSData *)data error:(NSError **)error;
+
+/**
+ * Decrypt encryped data using the account private key
+ * @param data The encrypted data
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The decrypted data
+ */
 - (nullable NSData *)decrypt:(NSData *)data error:(NSError **)error;
+
+/**
+ * @param error Error a reference to an error pointer that will be set in the case of an error
+ * @return The Contact object representing the Textile account
+ */
 - (Contact *)contact:(NSError **)error;
+
+/**
+ * Syncs the local node account with all thread snapshots found on the network
+ * @param options The query options to configure the behavior of the account sync
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return A handle that can be used to cancel the account sync
+ */
 - (MobileSearchHandle *)sync:(QueryOptions *)options error:(NSError **)error;
 
 @end

diff --git a/Textile/Classes/CafesApi.h b/Textile/Classes/CafesApi.h
@@ -11,13 +11,53 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile cafes related APIs
+ */
 @interface CafesApi : NodeDependant
 
+/**
+ * Used to register a remote Textile Cafe node with the local Textile node
+ * @param host The fully qualified host URL
+ * @param token The API token for the cafe being registered
+ * @param error A reference to an error pointer that will be set in the case of an error
+ */
 - (void)register:(NSString *)host token:(NSString *)token error:(NSError **)error;
+
+/**
+ * Fetches the CafeSession object for a previously registered Textile Cafe node
+ * @param peerId The peer id of the previously registered cafe node
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The CafeSession for the previousl registered cafe
+ */
 - (CafeSession *)session:(NSString *)peerId error:(NSError **)error;
+
+/**
+ * Used to get sessions for all previously registered Textile Cafes
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return An object containing a list of cafe sessions
+ */
 - (CafeSessionList *)sessions:(NSError **)error;
+
+/**
+ * Used to refresh an individual Textile Cafe session
+ * @param peerId The peer id of the cafe who's session you want to refresh
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The refreshed cafe session
+ */
 - (CafeSession *)refreshSession:(NSString *)peerId error:(NSError **)error;
+
+/**
+ * Used to deregister a previously registered Textile Cafe
+ * @param peerId The peer id of the cafe you want to deregister
+ * @param error A reference to an error pointer that will be set in the case of an error
+ */
 - (void)deregister:(NSString *)peerId error:(NSError **)error;
+
+/**
+ * Triggers the async process of cheking for messages from all registered cafes
+ * @param error A reference to an error pointer that will be set in the case of an error
+ */
 - (void)checkMessages:(NSError **)error;
 
 @end

diff --git a/Textile/Classes/CommentsApi.h b/Textile/Classes/CommentsApi.h
@@ -10,8 +10,18 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile comments related APIs
+ */
 @interface CommentsApi : NodeDependant
 
+/**
+ * Add a comment to any block by id
+ * @param blockId The id of the block you want to add a comment to
+ * @param body The text of the comment to add
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The id of the new comment block
+ */
 - (NSString *)add:(NSString *)blockId body:(NSString *)body error:(NSError **)error;
 
 @end

diff --git a/Textile/Classes/ContactsApi.h b/Textile/Classes/ContactsApi.h
@@ -12,13 +12,55 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile contacts related APIs
+ */
 @interface ContactsApi : NodeDependant
 
+/**
+ * Add a new Contact to the account's list of Contacts
+ * @param contact The new contact to add, usually returned from a Contact search
+ * @param error A reference to an error pointer that will be set in the case of an error
+ */
 - (void)add:(Contact *)contact error:(NSError **)error;
+
+/**
+ * Get a Contact by address from list of existing Contacts
+ * @param address The address of the Contact to retrieve
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The Contact object corresponding to the address
+ */
 - (Contact *)get:(NSString *)address error:(NSError **)error;
+
+/**
+ * List all exisiting account Contacts
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return An object containing a list of all account contacts
+ */
 - (ContactList *)list:(NSError **)error;
+
+/**
+ * Remove a Contact from the account by address
+ * @param address The address of the contact to remove
+ * @param error A reference to an error pointer that will be set in the case of an error
+ */
 - (void)remove:(NSString *)address error:(NSError **)error;
+
+/**
+ * List all threads a particular contact and the local node account participate in
+ * @param address The contact address to find threads for
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return An object containing a list of all threads the contact and the local node account participate in
+ */
 - (ThreadList *)threads:(NSString *)address error:(NSError **)error;
+
+/**
+ * Search for Textile Contacts across the entire network
+ * @param query A query object describing the search to execute
+ * @param options A query options object to control the behavior of the search
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return A handle that can be used to cancel the search
+ */
 - (MobileSearchHandle *)search:(ContactQuery *)query options:(QueryOptions *)options error:(NSError **)error;
 
 @end

diff --git a/Textile/Classes/FeedApi.h b/Textile/Classes/FeedApi.h
@@ -11,8 +11,17 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile feed related APIs
+ */
 @interface FeedApi : NodeDependant
 
+/**
+ * List thread items using a Feed view of the data, useful for timeline based views of thread data
+ * @param request An object that configures the request for feed data
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return An object that contains a list of feed items
+ */
 - (FeedItemList *)list:(FeedRequest *)request error:(NSError **)error;
 
 @end

diff --git a/Textile/Classes/FilesApi.h b/Textile/Classes/FilesApi.h
@@ -13,16 +13,90 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile files related APIs
+ */
 @interface FilesApi : NodeDependant
 
+/**
+ * Prepare raw data to later add to a Textile thread
+ * @param data Raw base64 string data
+ * @param threadId The thread id the data will be added to
+ * @param completion A block that will get called with the results of the prepare operation
+ */
 - (void)prepare:(NSString *)data threadId:(NSString *)threadId completion:(void (^)(MobilePreparedFiles * _Nullable, NSError *))completion;
+
+/**
+ * Prepare file data to later add to a Textile thread
+ * @param path The path to the file containing the data to prepare
+ * @param threadId The thread id the data will be added to
+ * @param completion A block that will get called with the results of the prepare operation
+ */
 - (void)prepareByPath:(NSString *)path threadId:(NSString *)threadId completion:(void (^)(MobilePreparedFiles * _Nullable, NSError *))completion;
+
+/**
+ * Prepare raw data synchronously to later add to a Textile thread
+ * @param data Raw base64 string data
+ * @param threadId The thread id the data will be added to
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return An object containing data about the prepared files that will be used to add to the thread later
+ */
 - (MobilePreparedFiles *)prepareSync :(NSString *)data threadId:(NSString *)threadId error:(NSError **)error;
+
+/**
+ * Prepare file data synchronously to later add to a Textile thread
+ * @param path The path to the file containing the data to prepare
+ * @param threadId The thread id the data will be added to
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return An object containing data about the prepared files that will be used to add to the thread later
+ */
 - (MobilePreparedFiles *)prepareByPathSync:(NSString *)path threadId:(NSString *)threadId error:(NSError **)error;
+
+/**
+ * Add data to a Textile thread
+ * @param directory The Directory data that was previously prepared
+ * @param threadId The thread to add the data to
+ * @param caption A caption to associate with the data
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The Block representing the added data
+ */
 - (Block *)add:(Directory *)directory threadId:(NSString *)threadId caption:(nullable NSString *)caption error:(NSError **)error;
+
+/**
+ * Add data from a Textile thread to another Textile thread
+ * @param target The target from the source thread of the data to add
+ * @param threadId The thread to add the data to
+ * @param caption A caption to associate with the data
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The Block representing the added data
+ */
 - (Block *)addByTarget:(NSString *)target threadId:(NSString *)threadId caption:(nullable NSString *)caption error:(NSError **)error;
+
+/**
+ * Get a list of files data from a thread
+ * @param threadId The thread to query
+ * @param offset The offset to beging querying from
+ * @param limit The max number of results to return
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return An object containing a list of files data
+ */
 - (FilesList *)list:(NSString *)threadId offset:(nullable NSString *)offset limit:(long)limit error:(NSError **)error;
+
+/**
+ * Get raw data for a file hash
+ * @param hash The hash to return data for
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The base64 string of data
+ */
 - (NSString *)data:(NSString *)hash error:(NSError **)error;
+
+/**
+ * Helper function to return the most appropriate image data for a minimun image width
+ * @param path The IPFS path that includes image data for various image sizes
+ * @param minWidth The width of the image the data will be used for
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The base64 string of image data
+ */
 - (NSString *)imageDataForMinWidth:(NSString *)path minWidth:(long)minWidth error:(NSError **)error;
 
 @end

diff --git a/Textile/Classes/FlagsApi.h b/Textile/Classes/FlagsApi.h
@@ -10,8 +10,17 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile flags related APIs
+ */
 @interface FlagsApi : NodeDependant
 
+/**
+ * Flag any data by block
+ * @param blockId The id of the Block to flag
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The hash of the new flag block
+ */
 - (NSString *)add:(NSString *)blockId error:(NSError **)error;
 
 @end

diff --git a/Textile/Classes/IgnoresApi.h b/Textile/Classes/IgnoresApi.h
@@ -10,8 +10,17 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Provides access to Textile ignores related APIs
+ */
 @interface IgnoresApi : NodeDependant
 
+/**
+ * Ignore data by block
+ * @param blockId The id of the block you want to ignore
+ * @param error A reference to an error pointer that will be set in the case of an error
+ * @return The hash of the new ignore block
+ */
 - (NSString *)add:(NSString *)blockId error:(NSError **)error;
 
 @end