From e98c3b831a76fc86ca355ffc4e65c49ade88ed6f Mon Sep 17 00:00:00 2001 From: Blake Watters Date: Sun, 16 Sep 2012 13:56:18 -0400 Subject: [PATCH] Align formatting and fill in @name sections within the Search module documentation --- .../RKManagedObjectStore+RKSearchAdditions.h | 36 +++++----- Code/Search/RKSearchIndexer.h | 65 +++++++------------ Code/Search/RKSearchPredicate.h | 21 +++--- Code/Search/RKSearchTokenizer.h | 17 ++--- Code/Search/RKSearchWord.h | 8 ++- Code/Search/RKSearchWordEntity.h | 5 +- 6 files changed, 65 insertions(+), 87 deletions(-) diff --git a/Code/Search/RKManagedObjectStore+RKSearchAdditions.h b/Code/Search/RKManagedObjectStore+RKSearchAdditions.h index f6763571..39795e3e 100644 --- a/Code/Search/RKManagedObjectStore+RKSearchAdditions.h +++ b/Code/Search/RKManagedObjectStore+RKSearchAdditions.h @@ -22,46 +22,50 @@ #import "RKSearchIndexer.h" /** - The search additions category provides support for configuring search indexing - for entities in a managed object store. + The search additions category provides support for configuring search indexing for entities in a managed object store. */ @interface RKManagedObjectStore (RKSearchAdditions) +///------------------------------------------ +/// @name Adding Search Indexing to an Entity +///------------------------------------------ + /** Adds search indexing to the entity for the given name in the receiver's managed object model. - Invocation of this method will result in the entity for the given name being updated to include a new - to-many relationship with the name 'searchWords'. The receiver's search indexer will also be instructed - to begin monitoring changes to the specified entity's searchable attributes to maintain the collection - of search words. If no search indexer exists, a new + Invocation of this method will result in the entity for the given name being updated to include a new to-many relationship with the name `searchWords`. The receiver's search indexer will also be instructed to begin monitoring changes to the specified entity's searchable attributes to maintain the collection of search words. If no search indexer exists, a new @param entityName The name of the entity in the receiver's managed object model that should be made searchable. - @param attributes An array of NSAttributeDescription objects or NSString attribute names specifying the - NSStringAttributeType attributes that are to be indexed for searching. + @param attributes An array of `NSAttributeDescription` objects or `NSString` attribute names specifying the `NSStringAttributeType` attributes that are to be indexed for searching. - @warning Must be invoked before adding persistent stores as the managed object model will become - immutable once the persistent store coordinator is created. + @warning Must be invoked before adding persistent stores as the managed object model will become immutable once the persistent store coordinator is created. */ - (void)addSearchIndexingToEntityForName:(NSString *)entityName onAttributes:(NSArray *)attributes; +///----------------------------------- +/// @name Accessing the Search Indexer +///----------------------------------- + /** The search indexer for the receiver's primary managed object context. - A search indexer is instantiated when search indexing is added to an entity - in the receiver's managed object model. + A search indexer is instantiated when search indexing is added to an entity in the receiver's managed object model. */ @property (nonatomic, readonly) RKSearchIndexer *searchIndexer; +///------------------------------------------ +/// @name Managing Automatic Context Indexing +///------------------------------------------ + /** - Tells the search indexer to begin observing the primary managed object context for changes to searchable - entities and updating the search words. + Tells the search indexer to begin observing the primary managed object context for changes to searchable entities and updating the search words. This is a convenience method that is equivalent to the following example code: RKSearchIndexer *searchIndexer = managedObjectStore.searchIndexer; [searchIndexer startObservingManagedObjectContext:managedObjectStore.primaryManagedObjectContext]; - @see RKSearchIndexer + @see `RKSearchIndexer` */ - (void)startIndexingPrimaryManagedObjectContext; @@ -73,7 +77,7 @@ RKSearchIndexer *searchIndexer = managedObjectStore.searchIndexer; [searchIndexer stopObservingManagedObjectContext:managedObjectStore.primaryManagedObjectContext]; - @see RKSearchIndexer + @see `RKSearchIndexer` */ - (void)stopIndexingPrimaryManagedObjectContext; diff --git a/Code/Search/RKSearchIndexer.h b/Code/Search/RKSearchIndexer.h index 3353cdb5..3947bb12 100644 --- a/Code/Search/RKSearchIndexer.h +++ b/Code/Search/RKSearchIndexer.h @@ -21,98 +21,79 @@ #import /** - The key for an NSArray object that indentifies the list of searchable - attributes in the user info dictionary of an NSEntityDescription. + The key for an NSArray object that indentifies the list of searchable attributes in the user info dictionary of an NSEntityDescription. */ extern NSString * const RKSearchableAttributeNamesUserInfoKey; /** - The `RKSearchIndexer` class provides support for adding full text searching - to Core Data entities and managing the indexing of managed object instances - of searchable entities. + The `RKSearchIndexer` class provides support for adding full text searching to Core Data entities and managing the indexing of managed object instances of searchable entities. */ @interface RKSearchIndexer : NSObject -///----------------------------------------------------------------------------- +///----------------------------------- /// @name Adding Indexing to an Entity -///----------------------------------------------------------------------------- +///----------------------------------- /** - Adds search indexing to the given entity for a given list of attributes identified by - name. The entity will have a to-many relationship to the RKSearchWordEntity added and - the list of searchable attributes stored into the user info dictionary. + Adds search indexing to the given entity for a given list of attributes identified by name. The entity will have a to-many relationship to the `RKSearchWordEntity` added and the list of searchable attributes stored into the user info dictionary. - Managed objects for entities that have had indexing added to them can be indexed by instances of - RKSearchIndexer and searched via an RKSearchPredicate in a fetch request. + Managed objects for entities that have had indexing added to them can be indexed by instances of `RKSearchIndexer` and searched via an `RKSearchPredicate` used with an `NSFetchRequest` object. - The given entity must exist in a mutable managed object model (that is, one that has not - been used to create an object graph in a managed object context). The given list of attributes - must identify attributes of the given entity with the attribute type of NSStringAttributeType. + The given entity must exist in a mutable managed object model (that is, one that has not been used to create an object graph in a managed object context). The given list of attributes must identify attributes of the given entity with the attribute type of `NSStringAttributeType`. @param entity The entity to which search indexing support is to be added. - @param attributes An array of NSAttributeDescription objects or NSString attribute names specifying the - NSStringAttributeType attributes that are to be indexed for searching. + @param attributes An array of NSAttributeDescription objects or NSString attribute names specifying the `NSStringAttributeType` attributes that are to be indexed for searching. */ + (void)addSearchIndexingToEntity:(NSEntityDescription *)entity onAttributes:(NSArray *)attributes; -///----------------------------------------------------------------------------- +///--------------------------- /// @name Configuring Indexing -///----------------------------------------------------------------------------- +///--------------------------- /** - An optional set of stop words to be removed from the set of tokens - used to create the search words for indexed entities. + An optional set of stop words to be removed from the set of tokens used to create the search words for indexed entities. */ @property (nonatomic, strong) NSSet *stopWords; -///----------------------------------------------------------------------------- +///--------------------------------------------------- /// @name Indexing Changes in a Managed Object Context -///----------------------------------------------------------------------------- +///--------------------------------------------------- /** - Tells the receiver to tart monitoring the given managed object context for the - NSManagedObjectContextWillSaveNotification and to index any changed objects prior - to the completion of the save. + Tells the receiver to tart monitoring the given managed object context for the `NSManagedObjectContextWillSaveNotification` and to index any changed objects prior to the completion of the save. @param managedObjectContext The managed object context to be monitored for save notifications. - @see indexChangedObjectsInManagedObjectContext: + @see `indexChangedObjectsInManagedObjectContext:` */ - (void)startObservingManagedObjectContext:(NSManagedObjectContext *)managedObjectContext; /** - Tells the receiver to stop monitoring the given managed object context for the - NSManagedObjectContextWillSaveNotification and cease indexing changed objects prior to - the completion of the save. + Tells the receiver to stop monitoring the given managed object context for the `NSManagedObjectContextWillSaveNotification` and cease indexing changed objects prior to the completion of the save. - @param managedObjectContext The managed object context that is no longer to be monitored for - save notifications. + @param managedObjectContext The managed object context that is no longer to be monitored for save notifications. */ - (void)stopObservingManagedObjectContext:(NSManagedObjectContext *)managedObjectContext; /** - Tells the receiver to build a list of all inserted or updated managed objects in the given - context and index each one. Objects for entities that are not indexed are silently ignored. + Tells the receiver to build a list of all inserted or updated managed objects in the given context and index each one. Objects for entities that are not indexed are silently ignored. - Invoked by the indexer in response to a NSManagedObjectContextWillSaveNotification if the - context is being observed. + Invoked by the indexer in response to a `NSManagedObjectContextWillSaveNotification` if the context is being observed. @param managedObjectContext The managed object context that is to be indexed. */ - (void)indexChangedObjectsInManagedObjectContext:(NSManagedObjectContext *)managedObjectContext; -///----------------------------------------------------------------------------- +///-------------------------------- /// @name Indexing a Managed Object -///----------------------------------------------------------------------------- +///-------------------------------- /** Tells the receiver to index a given managed object instance. @param managedObject The managed object that is to be indexed. - @return A count of the number of search words that were indexed from the given object's - searchable attributes. - @raises NSInvalidArgumentException Raised if the given managed object is not for a searchable - entity. + @return A count of the number of search words that were indexed from the given object's searchable attributes. + @raises `NSInvalidArgumentException` Raised if the given managed object is not for a searchable entity. */ - (NSUInteger)indexManagedObject:(NSManagedObject *)managedObject; diff --git a/Code/Search/RKSearchPredicate.h b/Code/Search/RKSearchPredicate.h index dae72753..cebb6518 100644 --- a/Code/Search/RKSearchPredicate.h +++ b/Code/Search/RKSearchPredicate.h @@ -21,18 +21,18 @@ #import /** - RKSearchPredicate is a suclass of NSCompoundPredicate used to represent - textual search operations against entities indexed by an instance of RKSearchIndexer. + `RKSearchPredicate` is a suclass of `NSCompoundPredicate` used to represent textual search operations against entities indexed by an instance of `RKSearchIndexer`. - @see RKSearchIndexer + @see `RKSearchIndexer` */ @interface RKSearchPredicate : NSCompoundPredicate +///---------------------------------- +/// @name Creating a Search Predicate +///---------------------------------- + /** - Creates and returns a new predicate for performing a full text search on an entity indexed - by an instance of RKSearchIndexer. The given search text will be tokenized, normalized and - used to construct a collection of subpredicates specifying a BEGINSWITH match against the - searchWords relationship of the searchable entity. + Creates and returns a new predicate for performing a full text search on an entity indexed by an instance of `RKSearchIndexer`. The given search text will be tokenized, normalized and used to construct a collection of subpredicates specifying a `BEGINSWITH` match against the searchWords relationship of the searchable entity. @param searchText A string of text with which to construct subpredicates for searching. @param type The type of the new compound predicate. @@ -43,14 +43,11 @@ /** Initializes the receiver with a string of search text and a compound predicate type. - The search text will be tokenized, normalized and then used to construct an array of - subpredicates specifying a BEGINSWITH match against the searchWords relationship of the - searchable entity. + The search text will be tokenized, normalized and then used to construct an array of subpredicates specifying a `BEGINSWITH` match against the `searchWords` relationship of the searchable entity. @param searchText A string of text with which to construct subpredicates for searching. @param type The type of the new compound predicate. - @return The receiver with its type set to the given type and its subpredicates set to an - array of subpredicates for searching for the given text. + @return The receiver with its type set to the given type and its subpredicates set to an array of subpredicates for searching for the given text. */ - (id)initWithSearchText:(NSString *)searchText type:(NSCompoundPredicateType)type; diff --git a/Code/Search/RKSearchTokenizer.h b/Code/Search/RKSearchTokenizer.h index ff7d4139..aa6dcffa 100644 --- a/Code/Search/RKSearchTokenizer.h +++ b/Code/Search/RKSearchTokenizer.h @@ -21,16 +21,13 @@ #import /** - The RKSearchTokenizer class provides an interface for tokenizing input - text into a set of searchable words. Diacritics are removed and the input - text is tokenized case insensitively. A set of stop words can be optionally - trimmed from the result token set. + The `RKSearchTokenizer` class provides an interface for tokenizing input text into a set of searchable words. Diacritics are removed and the input text is tokenized case insensitively. A set of stop words can be optionally trimmed from the result token set. */ @interface RKSearchTokenizer : NSObject -///----------------------------------------------------------------------------- +///------------------------------- /// @name Configuring Tokenization -///----------------------------------------------------------------------------- +///------------------------------- /** The set of stop words that are to be removed from the token set. @@ -39,14 +36,12 @@ */ @property (nonatomic, strong) NSSet *stopWords; -///----------------------------------------------------------------------------- +///---------------------------------- /// @name Tokenizing a String of Text -///----------------------------------------------------------------------------- +///---------------------------------- /** - Tokenizes the given string by folding it case and diacritic insensitively and then - splitting it apart using the the word unit delimiters for the current locale. If a set - of stop words has been provided, the resulting token set will have the stop words subtracted. + Tokenizes the given string by folding it case and diacritic insensitively and then splitting it apart using the the word unit delimiters for the current locale. If a set of stop words has been provided, the resulting token set will have the stop words subtracted. @param string A string of text you wish to tokenize. @returns A set of searchable text tokens extracted from the given string. diff --git a/Code/Search/RKSearchWord.h b/Code/Search/RKSearchWord.h index 7623d6e7..661b833b 100644 --- a/Code/Search/RKSearchWord.h +++ b/Code/Search/RKSearchWord.h @@ -21,14 +21,16 @@ #import /* - RKSearchWord implements a managed object subclass for representing - search words contained in designated string attributes of entities indexed - by an instance of RKSearchIndexer. + RKSearchWord implements a managed object subclass for representing search words contained in designated string attributes of entities indexed by an instance of RKSearchIndexer. @see RKSearchIndexer */ @interface RKSearchWord : NSManagedObject +///------------------------------------------ +/// @name Accessing the Search Word Attribute +///------------------------------------------ + /** A single search word extracted from an indexed entity. */ diff --git a/Code/Search/RKSearchWordEntity.h b/Code/Search/RKSearchWordEntity.h index 5828516d..a3a42dab 100644 --- a/Code/Search/RKSearchWordEntity.h +++ b/Code/Search/RKSearchWordEntity.h @@ -24,9 +24,8 @@ extern NSString * const RKSearchWordEntityName; extern NSString * const RKSearchWordAttributeName; extern NSString * const RKSearchWordsRelationshipName; -/** - Defines a Core Data entity for representing searchable text - content in a managed object model. +/* + Defines a Core Data entity for representing searchable text content in a managed object model. */ @interface RKSearchWordEntity : NSEntityDescription