Align formatting and fill in @name sections within the Search module documentation

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;
 

Code/Search/RKSearchIndexer.h

@@ -21,98 +21,79 @@
 #import <CoreData/CoreData.h>
 
 /**
- 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;
 

Code/Search/RKSearchPredicate.h

@@ -21,18 +21,18 @@
 #import <Foundation/Foundation.h>
 
 /**
- 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;
 

Code/Search/RKSearchTokenizer.h

@@ -21,16 +21,13 @@
 #import <Foundation/Foundation.h>
 
 /**
- 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.

Code/Search/RKSearchWord.h

@@ -21,14 +21,16 @@
 #import <CoreData/CoreData.h>
 
 /*
- 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.
  */

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