Added Documentation

MathKit/MPParsedExpression.h

@@ -13,24 +13,97 @@
 
 /*!
     @const      MPMathKitErrorDomain
-    @brief      Predefined error domain for errors from the MathKit framework.
+    @abstract   Predefined error domain for errors from the MathKit framework.
  
-    @discussion Errors in MathKit can occur during parsing of expressions or
-                during evaluation of expressions. These two can be distinguished
- by the error code. Parsing errors have lower error codes.
- Evaluation errors (math errors) have error codes from @c 100 upwards.
+    @discussion Errors in MathKit can occur during parsing or evaluation of
+                expressions. These two can be distinguished by their respective
+                error codes. Parsing errors have error codes below
+                <code>100</code>. Evaluation errors (math errors) on the other
+                hand have error codes from <code>100</code> upwards.
  */
 FOUNDATION_EXPORT NSString *const MPMathKitErrorDomain;
 
+
+/*!
+    @const      MPPathToExpressionKey
+    @abstract   Predefined key for the path to the expression that caused an error.
+ 
+    @discussion Parsing errors in the <code>MPMathKitErrorDomain</code> have a
+                value for this key in their <code>userInfo</code> dictionary. The
+                value is of type <code>NSIndexPath</code>. The root of that path
+                is also the root expression of the expression tree of the
+                expression that was parsed (which in turn caused an error).
+ */
 FOUNDATION_EXPORT NSString *const MPPathToExpressionKey;
+
+
+/*!
+    @const      MPErrorRangeKey
+    @abstract   Predefined key for the range inside an expression that caused a
+                parsing error.
+ 
+    @discussion Parsing errors in the <code>MPMathKitErrorDomain</code> have a
+                value for this key in their <code>userInfo</code> dictionary. The
+                value is a <code>NSRange</code> value wrapped in a
+                <code>NSValue</code> object.
+ */
 FOUNDATION_EXPORT NSString *const MPErrorRangeKey;
 
 
+/*!
+    @class      MPParsedExpression
+    @abstract   A parsed expression represents an expression whose syntax is
+                mathematically valid and thus can be evaluated.
+ 
+    @discussion This class should not be instanciated directly. Instead you
+                should use the <code>parse...</code> methods from the <code>@link
+                //apple_ref/occ/cl/MPExpression@/link</code> class. A
+                successfully parsed expression can still fail to be evaluated if
+                it contains mathematically undefined expressions.
+ */
 @interface MPParsedExpression : NSObject
 
+/*!
+    @property   definedVariable
+    @abstract   The variable defined by the expression, if any.
+ 
+    @discussion If a variable was defined this property is a string of length
+                <code>1</code> containing the name of that variable. If no
+                variable was defined this property is <code>nil</code>.
+ 
+                This property should not be set manually.
+ */
 @property (nonatomic, strong) NSString *definedVariable;
+
+
+/*!
+    @property   term
+    @abstract   The receiver's evaluatable term.
+ 
+    @discussion The term may still contain mathematicall undefined expressions.
+ 
+                This property should not be set manually.
+ */
 @property (nonatomic, strong) MPTerm *term;
 
+
+/*!
+    @method     evaluate:
+    @abstract   Evaluates the receiver.
+
+    @discussion This method is a convenience method for evaluating the receiver's
+                <code>@link
+                //apple_ref/occ/intfp/MPParsedExpression/term@/link</code>.
+ 
+    @param      error
+                If an error occured during evaluation it will be returned
+                indirectly through this parameter. If you are not interested in
+                errors pass <code>NULL</code>.
+ 
+    @return     A <code>NSDecimalNumber</code> containing the result of the
+                evaluation. Depending on the evaluated expression the result may
+                only be of double precision.
+ */
 - (NSDecimalNumber *)evaluate:(NSError *__autoreleasing *)error;
 
 @end