Added Documentation

MathPad/MPExpressionTreeElement.h

@@ -5,16 +5,85 @@
 //  Created by Kim Wittenburg on 09.10.14.
 //  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
 //
+// TODO: Replace internal inconsistency exception with something else
+
+
 
 @class MPTokenStream;
 
+
+/*!
+    @protocol   MPExpressionTreeElement
+    @brief      This protocol defines the methods that are essential for dealing
+                with an expression in a mathematical context.
+ 
+    @discussion Dealing with an expression in a mathematical context involves
+                anything from evaluation to transformation of expressions and
+                equations.
+ */
 @protocol MPExpressionTreeElement <NSObject>
 @required
 
-- (instancetype)init;
+
+/*!
+    @method     initWithTokenStream:
+    @brief      Initializes the expression tree element from the given token
+                strem.
+ 
+    @discussion This method consumes the tokens that make up this element. If the
+                token stream does not start with a token that is appropriate for
+                the initializied expression tree element a @c
+                NSInternalInconsistency exception is raised.
+ 
+    @param      tokenStream
+                The token stream the receiver is to be initialized from.
+ 
+    @return     A new instance.
+ */
 - (instancetype)initWithTokenStream:(MPTokenStream *)tokenStream;
 
+
+/*!
+    @method     validate:
+    @brief      Validates the receiver.
+ 
+    @discussion Validation should only check for syntax errors. Mathematical
+                errors like a division by @c 0 should be handled with in @c
+                -evaluate.
+ 
+    @param      error
+                If there is a syntax error in the receiver this parameter should
+                be set to an appropriate value. If you are not interested in the
+                type of syntax error pass @c NULL.
+ 
+    @return     @c YES if the receiver is valid, @c NO otherwise. If @c NO is
+                returned the @c error parameter should be set to an appropriate
+                value.
+ */
 - (BOOL)validate:(NSError *__autoreleasing *)error;
-- (NSDecimalNumber *)evaluate;
+
+
+/*!
+    @method     evaluate:
+    @brief      Evaluates the receiver.
+ 
+    @discussion Evaluation does not take syntax errors into account. Before this
+                method is called you must call @c validate: to make sure that the
+                reciever is valid for evaluation. The result of evaluation with
+                @c -validate: returning @c NO may be unexpected or evaluation may
+                completely fail.
+ 
+    @param      error
+                If any errors occur during evaluation (such as division by zero)
+                this parameter will be set to an appropriate value. If you are
+                not interested in errors pass @c NULL.
+       @warning This method is not responsible for syntax validation. Use @c
+                -validate: instead.
+ 
+    @return     The result of the evaluationa or @c nil or @c NaN if evaluation
+                fails. If evaluation fails the @c error parameter will be set to
+                an apporpriate value.
+ */
+- (NSDecimalNumber *)evaluate:(NSError *__autoreleasing *)error;
 
 @end