Added Documentation

MathPad/MPTokenStream.h

@@ -6,23 +6,132 @@
 //  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
 //
 
+
+
 @class MPTokenStream;
 @protocol MPToken;
 
+
+/*!
+    @class      MPTokenStream
+    @brief      This class is a helper class for processing tokens from the
+                beginning of an expression to the end.
+ 
+    @discussion A token stream is a single-use object. After the stream has
+                reached the end there is no way to reset it.
+ */
 @interface MPTokenStream : NSObject
 
-- (instancetype)initWithTokens:(NSArray *)tokens;
 
-@property (nonatomic, copy) NSArray *tokens;
+/*!
+    @method     initWithTokens:
+    @brief      Creates a new token stream that @em streams the contents of the
+            	@c tokens array.
+ 
+    @param      tokens
+                The tokens to be @em streamed. All objects in the array must
+                conform to the @c MPToken protocol.
+ 
+    @return     A new token stream.
+ */
+- (instancetype)initWithTokens:(NSArray *)tokens; /* designated initializer */
 
+
+/*!
+    @method     beginIgnoringWhitespaceTokens
+    @brief      After calling this method a @c -currentToken message will skip
+                whitespace characters before returning the current token.
+ 
+    @discussion Any call to this method or @c -beginAcceptingWhitespaceTokens
+                must be matched by a @c -endIgnoringOrAcceptingWhitespaceTokens
+                message. Calls to both methods can be nested.
+ 
+                By default whitespace tokens are accepted.
+ 
+    @see        -beginAcceptingWhitespaceTokens
+    @see        -endIgnoringOrAcceptingWhitespaceTokens
+ */
 - (void)beginIgnoringWhitespaceTokens;
+
+
+/*!
+    @method     beginAcceptingWhitespaceTokens
+    @brief      After calling this method @c -currentToken may return a token of
+                type @c MPWhitespaceToken.
+ 
+    @discussion Any call to this method or @c -beginAcceptingWhitespaceTokens
+                must be matched by a @c -endIgnoringOrAcceptingWhitespaceTokens
+                message. Calls to both methods can be nested.
+ 
+                By default whitespace tokens are accepted.
+ 
+    @see        -beginIgnoringWhitespaceTokens
+    @see        -endIgnoringOrAcceptingWhitespaceTokens
+ */
 - (void)beginAcceptingWhitespaceTokens;
+
+
+/*!
+    @method     endIgnoringOrAcceptingWhitespaceTokens
+    @brief      This method balances @c -beginIgnoringWhitespaceTokens and @c
+                -beginAcceptingWhitespaceTokens messages.
+ 
+    @discussion After this method was
+                calles the whitespace behaviour falls back to the way it behaved
+                before the last @c -beginIgnoringWhitespaceTokens or @c
+                -beginAcceptingWhitespaceTokens message was sent.
+ */
 - (void)endIgnoringOrAcceptingWhitespaceTokens;
 
+
+
+/*!
+    @method     hasMoreTokens
+    @brief      Use this method to check wether there are any tokens left.
+ 
+    @discussion This method repects the whitespace skipping behaviour. That means
+                that if the token stream currently ignores whitespaces and there
+                are only whitespaces left in the stream this method returns @c
+                NO.
+ 
+    @return     @c YES if there are more tokens, @c NO otherwise.
+ */
 - (BOOL)hasMoreTokens;
 
+
+/*!
+    @method     currentToken
+    @brief      Returns the receiver's current token.
+ 
+    @discussion This is one of the core methods of @c MPTokenStream. Subsequent
+                calls to this method will return the same value until @c
+                -currentTokenConsumed is called.
+ 
+    @return     The current token or @c nil if there are no more tokens.
+ */
 - (id<MPToken>)currentToken;
+
+
+/*!
+    @method     peekNextToken
+    @brief      Looks at the next token and returns it.
+ 
+    @discussion This method behaves as if you called @c -currentTokenConsumed
+                followed by @c -currentToken except that it does not consume the
+                current token. That means that you can use this method to look at
+                the next token (respecting the current whitespace ignoring
+                behaviour) without changing the @c currentToken.
+
+    @return     The next token or @c nil if there is no token after the current
+                one.
+ */
 - (id<MPToken>)peekNextToken;
+
+
+/*!
+    @method     currentTokenConsumed
+    @brief      Marks the current token as consumed and discards it.
+ */
 - (void)currentTokenConsumed;
 
 @end