Added Lots of Documentation

Added some nice to haves
Improved and Unified General Code Layout

MathKit/MPEvaluationContext.h

@@ -7,21 +7,117 @@
 //
 
 
+/*!
+ @header
+ This file contains the <code>MPEvaluationContext</code> class.
+ 
+ The evaluation context is organized in so called levels. Every level of a
+ context contains a unique set of variables. Only the highest level is
+ accessible. Before any lower level can be accessed the higher ones have to be
+ discarded. A higher level can not define variables that are already defined in
+ a lower level. Similarly variables can only be undefined if they are defined at
+ the current level. Discarding (popping) a level always undefines all variables
+ defined on that level.
+ */
+
+
 
 @class MPEvaluationContext;
 
 
+/*!
+    @class      MPEvaluationContext
+    @abstract   The evaluation context maintains a map of variables and
+                associates them with a certain level.
+ 
+    @discussion Different levels are nested using <code>@link
+                //apple_ref/occ/instm/MPEvaluationContext/push@/link</code> and
+                <code>@link
+                //apple_ref/occ/instm/MPEvaluationContext/pop@/link</code>
+                messages.
+ 
+                <code>MPEvaluationContext</code> is a singletone class. There can
+                only exist one instance (the shared instance) at any time.
+ */
 @interface MPEvaluationContext : NSObject
 
+/*!
+    @method     sharedContext
+    @abstract   Returns the shared evaluation context.
+ */
 + (MPEvaluationContext *)sharedContext;
 
+
+/*!
+    @method     push
+    @abstract   Pushes a new level on context.
+ */
 - (void)push;
+
+
+/*!
+    @method     pop
+    @abstract   Pops a level off the context.
+ 
+    @discussion Popping a level also undefines all variables that were defined in
+                that level.
+ */
 - (void)pop;
 
+
+/*!
+    @method     defineVariable:value:
+    @abstract   Defines a variable with the specified value at the current level.
+ 
+    @discussion The variable can only be defined if it has not been defined
+                previously in a lower level. If the variable has been defined at
+                the current level its value will be overwritten to the specified
+                one.
+ 
+    @param      variable
+                The name of the variable. Typically this is a one-letter string.
+ 
+    @param      value
+                The value of the variable.
+ 
+    @return     <code>YES</code> if the variable was defined successfully,
+                <code>NO</code> if it is already defined in a lower level.
+ */
 - (BOOL)defineVariable:(NSString *)variable
                  value:(NSDecimalNumber *)value;
+
+
+/*!
+    @method     undefineVariable:
+    @abstract   Undefines a variable that has previously been defined.
+ 
+    @discussion Variables can only be undefined if they have been defined at the
+                same level. If the variable to be undefined was defined at a
+                different level this method does nothing.
+ 
+                Normally there is very little reason to call this method since
+                all variables defined on one level are automatically undefined
+                when the level is popped.
+ 
+    @param      variable
+                The variable to be undefined.
+ */
 - (void)undefineVariable:(NSString *)variable;
 
+
+/*!
+    @method     valueForVariable:
+    @abstract   Returns the value for the specified variable.
+ 
+    @discussion If the <code>variable</code> has not been defined previously this
+                method returns <code>nil</code>.
+ 
+    @param      variable
+                The variable whose value is to be retrieved.
+ 
+    @return     The value <code>variable</code> was defined with or
+                <code>nil</code> if it was not defined.
+ */
 - (NSDecimalNumber *)valueForVariable:(NSString *)variable;
 
 @end