NSSpellServer documentation.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@18326 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,8 @@
+2004-01-06 23:39  Gregory John Casamento  <greg_casamento@yahoo.com>
+
+	* Source/NSSpellServer.m: Documentation.
+	* Headers/AppKit/NSSpellServer.h: Documentation.
+	
 2004-01-06 21:58  Gregory John Casamento  <greg_casamento@yahoo.com>
 
 	* Source/NSAffineTransform.m: More documentation.

Headers/AppKit/NSSpellServer.h

@@ -66,28 +66,54 @@
 		   caseSensitive:(BOOL)flag;
 @end
 
-//
-// NOTE: This is an informal protocol since the
-//  NSSpellChecker will need to use a proxy object
-//  to call these methods.   If they are defined on
-//  NSObject, then the compiler won't complain
-//  about not being able to find the method. (GJC)
-//
+/**
+  This is an informal protocol since the
+  NSSpellChecker will need to use a proxy object
+  to call these methods.  
+
+  These methods need to be implemented by the spell service
+  so that the NSSpellServer instance call call them when
+  necessary.
+*/
 @interface NSObject (NSSpellServerDelegate)
+/**
+ * <p>
+ * This method is called when the user begins spell checking the document.
+ * The parameters are: <code>sender</code> the spell server instance which
+ * invoked this method, <code>stringToCheck</code> this is the string which
+ * the spell service is going to attempt to find misspelled words in,
+ * <code>language</code> the language to check in, <code>wordCount</code> the
+ * number of words checked, and <code>countOnly</code> a flag which dictates
+ * if them method checks the spelling or just counts the words in the given
+ * string.
+ * </p>
+ * <p>
+ * Returns a range for any word it finds that is misspelled.
+ * </p>
+ */
 - (NSRange)spellServer:(NSSpellServer *)sender
 findMisspelledWordInString:(NSString *)stringToCheck
                   language:(NSString *)language
                  wordCount:(int *)wordCount
                  countOnly:(BOOL)countOnly;
 
+/**
+ * Attempts to guess the correct spelling of <code>word</code>. 
+ */
 - (NSArray *)spellServer:(NSSpellServer *)sender
    suggestGuessesForWord:(NSString *)word
               inLanguage:(NSString *)language;
 
+/**
+ * Records the new word in the user's dictionary for the given language.
+ */
 - (void)spellServer:(NSSpellServer *)sender
        didLearnWord:(NSString *)word
          inLanguage:(NSString *)language;
 
+/**
+ * Forgets the given word in the user's dictionary for the given language.
+ */
 - (void)spellServer:(NSSpellServer *)sender
       didForgetWord:(NSString *)word
          inLanguage:(NSString *)language;

Source/NSSpellServer.m

@@ -99,6 +99,11 @@ GSSpellServerName(NSString *vendor, NSString *language)
 }
 
 // Checking in Your Service 
+
+/**
+ * This method vends the spell server to the Distributed Objects system
+ * so that it can be connected to by clients.
+ */
 - (BOOL)registerLanguage:(NSString *)language
 		byVendor:(NSString *)vendor
 {
@@ -123,11 +128,22 @@ GSSpellServerName(NSString *vendor, NSString *language)
 }
 
 // Assigning a Delegate 
+
+/**
+ * Return the spell server delegate.
+ */ 
 - (id)delegate
 {
   return _delegate;
 }
 
+/**
+ * This method is used to set the delegate of the spellserver.
+ * When a spelling service is run the spell server is vended out
+ * to DO.  The spelling service must instantiate an instance of 
+ * this class and set itself to be the delegate.   This allows
+ * the service to respond to messages sent by the client.
+ */
 - (void)setDelegate:(id)anObject
 {
   /* FIXME - we should not retain the delegate ! */
@@ -136,6 +152,12 @@ GSSpellServerName(NSString *vendor, NSString *language)
 }
 
 // Running the Service 
+/**
+ * Initiate the run loop of this service.  Once the spell server
+ * object is vended, this method is called so that the server can
+ * start responding to the messages sent by the client.  These
+ * messages are passed on to the NSSpellServer instance's delegate.
+ */
 - (void)run
 {
   // Start the runloop explicitly.
@@ -144,6 +166,9 @@ GSSpellServerName(NSString *vendor, NSString *language)
 
 // Private method
 // Determine the path to the dictionary
+/**
+ * Path to the dictionary for the specified language.
+ */
 - (NSString *)_pathToDictionary: (NSString *)currentLanguage
 {
   NSString *path = nil;
@@ -201,7 +226,7 @@ GSSpellServerName(NSString *vendor, NSString *language)
 }
 
 // Private method
-// Open up dictionary stored in the user's directory.          
+/** Open up dictionary stored in the user's directory.   */
 - (NSMutableSet *)_openUserDictionary: (NSString *)language
 {
   NSString *path = nil;
@@ -233,6 +258,7 @@ GSSpellServerName(NSString *vendor, NSString *language)
 }
 
 // Checking User Dictionaries
+/** Check if word is in dict, flag determines if the search is case sensitive. */
 - (BOOL)_isWord: (NSString *)word
    inDictionary: (NSSet *)dict
   caseSensitive: (BOOL)flag
@@ -298,6 +324,10 @@ GSSpellServerName(NSString *vendor, NSString *language)
 }
 
 // Checking User Dictionaries
+/** 
+Checks to see if the word is in the user's dictionary.  The user dictionary
+is a set of words learned by the spell service for that particular user.
+*/
 - (BOOL)isWordInUserDictionaries:(NSString *)word
 		   caseSensitive:(BOOL)flag
 {
@@ -314,7 +344,7 @@ GSSpellServerName(NSString *vendor, NSString *language)
   return result;
 }
 
-// Save the dictionary stored in user's directory.
+/** Save the dictionary stored in user's directory. */
 - (BOOL)_saveUserDictionary: (NSString *)language
 {
   NSString *path = nil;
@@ -337,7 +367,7 @@ GSSpellServerName(NSString *vendor, NSString *language)
   return YES; 
 }
 
-// Learn a new word and put it into the dictionary
+/** Learn a new word and put it into the dictionary. */
 -(BOOL)_learnWord: (NSString *)word
      inDictionary: (NSString *)language
 {
@@ -360,7 +390,7 @@ GSSpellServerName(NSString *vendor, NSString *language)
   return [self _saveUserDictionary: language];
 }
 
-// Forget a word and remove it from the dictionary
+/** Forget a word and remove it from the dictionary. */
 -(BOOL)_forgetWord: (NSString *)word
       inDictionary: (NSString *)language
 {
@@ -383,7 +413,7 @@ GSSpellServerName(NSString *vendor, NSString *language)
   return [self _saveUserDictionary: language];
 }
 
-// Find a misspelled word
+/** Find a misspelled word. */
 - (NSRange)_findMisspelledWordInString: (NSString *)stringToCheck
 			      language: (NSString *)language
 			  ignoredWords: (NSArray *)ignoredWords
@@ -413,6 +443,7 @@ GSSpellServerName(NSString *vendor, NSString *language)
   return r;
 }
 
+/** Suggest a correction for the word. */
 - (NSArray *)_suggestGuessesForWord: (NSString *)word
 		       inLanguage: (NSString *)language
 {