--- parser3/src/include/pa_pool.h	2001/03/13 11:15:03	1.30
+++ parser3/src/include/pa_pool.h	2001/03/19 16:44:00	1.35
@@ -1,9 +1,9 @@
-/*
+/** @file
 	Parser
 	Copyright (c) 2001 ArtLebedev Group (http://www.artlebedev.com)
 	Author: Alexander Petrosyan <paf@design.ru> (http://design.ru/paf)
 
-	$Id: pa_pool.h,v 1.30 2001/03/13 11:15:03 paf Exp $
+	$Id: pa_pool.h,v 1.35 2001/03/19 16:44:00 paf Exp $
 */
 
 #ifndef PA_POOL_H
@@ -14,36 +14,33 @@
 class Exception;
 class Temp_exception;
 
+/** 
+	Pool mechanizm allows users not to free up allocated memory,
+	leaving that problem to 'pools'.
+
+	Also holds Exception object, which can be temporary set using 
+	Temp_exception auto-object.
+*/
+
 class Pool {
 	friend Temp_exception;
 public:
 
-	Pool() : 
-		fexception_to_trhow(0),
-		fpending_exception(0) {
-	}
+	Pool() : fexception(0) {}
 	~Pool() {}
 
-	Exception& exception_to_throw() const { return *fexception_to_throw; }
-	//Exception *pending_exception() const { return fpending_exception; }
+	/// current exception object of the pool
+	Exception& exception() const { return *fexception; }
 
+	/// allocates some bytes on pool
 	void *malloc(size_t size) {
 		return check(real_malloc(size), size);
 	}
+	/// allocates some bytes clearing them with zeros
 	void *calloc(size_t size) {
 		return check(real_calloc(size), size);
 	}
 
-	void maybe_rethrow_pending_exception() {
-		if(fpending_exception)
-			fexception_to_throw._throw(
-				fpending_exception.type(),
-				fpending_exception.code(),
-				fpending_exception.problem_source(),
-				fpending_exception.comment()
-			);
-	}
-
 private: // implementation defined
 
     void *real_malloc(size_t size);
@@ -51,7 +48,7 @@ private: // implementation defined
 
 private: 
 
-	// checks whether mem allocated OK. throws exception otherwise
+	/// checks whether mem allocated OK. throws exception otherwise
 	void *check(void *ptr, size_t size) {
 		if(ptr)
 			return ptr;
@@ -61,30 +58,26 @@ private:
 		// never reached
 		return 0;
 	}
-	// throws proper exception
+	/// throws proper exception
 	void fail(size_t size) const;
 
-protected: // exception handling
+private: // exception handling
 
 	// exception replacement mechanism is 'protected' from direct usage
-	// Temp_exception_change object enforces paired set/restore
+	// Temp_exception object enforces paired set/restore
 	Exception *set_exception(Exception *e){
-		Exception *r=fexception_to_throw;
-		fexception_to_throw=e;
+		Exception *r=fexception;
+		fexception=e;
 		return r;
 	}
 	void restore_exception(Exception *e) {
-		fpending_exception=fexception_to_throw.is_handled()?0:fexception_to_throw;
-		fexception_to_throw=e;
+		fexception=e;
 	}
 
 private:
 
 	// current request's exception object
-	Exception *fexception_to_throw;
-
-	// just catched request's exception object
-	Exception *fpending_exception;
+	Exception *fexception;
 
 private: //disabled
 
@@ -92,6 +85,11 @@ private: //disabled
 	Pool& operator = (const Pool&) { return *this; }
 };
 
+/** 
+	Base for all classes that are allocated in 'pools'.
+
+	Holds Pool object. Contains useful wrappers to it's methods.
+*/
 class Pooled {
 	// the pool i'm allocated on
 	Pool& fpool;
@@ -104,13 +102,36 @@ public:
 	Pooled(Pool& apool) : fpool(apool) {
 	}
 
+	/// my pool
 	Pool& pool() const { return fpool; }
 
+	/// useful wrapper around pool
 	void *malloc(size_t size) const { return fpool.malloc(size); }
+	/// useful wrapper around pool
 	void *calloc(size_t size) const { return fpool.calloc(size); }
+	/// useful wrapper around pool
+	Exception& exception() const { return fpool.exception(); }
 };
+/// useful macro for creating objects on current Pooled object Pooled::pool()
 #define NEW new(pool())
 
+/** 
+	Auto-object used for temporary changing Pool's exception().
+
+	Use by with these macros:
+	\code
+		TRY { 
+			... 
+			if(?) 
+				THROW(?); 
+			...;
+		} CATCH(e) { 
+			code, using e fields
+			e.comment() 
+		}
+		END_CATCH
+	\endcode
+*/
 class Temp_exception {
 	Pool& fpool;
 	Exception *saved_exception;
@@ -122,44 +143,36 @@ public:
 	~Temp_exception() { 
 		fpool.restore_exception(saved_exception); 
 	}
-public:
-	bool triggered;
 };
 
-#define XTRY(p) \
+#define XTRY(pool) \
 	{ \
 		Exception temp_exception; \
-		Temp_exception le(p, temp_exception); \
+		Temp_exception le(pool, temp_exception); \
 		if(setjmp(temp_exception.mark)==0)
-#define XTHROW(p) p.exception_to_throw()._throw
+
+#define XTHROW(exception) exception._throw
 #define XCATCH(e) \
 		else{ \
 			Exception& e=temp_exception;
-#define XFINALLY(p) \
+
+#define XEND_CATCH \
 		} \
-		p.maybe_rethrow_pending_exception();
-#define XEND_TRY \
 	}
 
-// usage:
-//   TRY { ...; if(?) RAISE(?); ...; } CATCH(e) { catch-code e.comment() } END_TRY
-
+//@{
+/// @see Temp_exception 
 #define TRY XTRY(pool())
-#define THROW XTHROW(pool())
+#define THROW XTHROW(exception())
 #define CATCH(e) XCATCH(e)
-#define FINALLY(p) XFINALLY(pool())
-#define END_TRY XEND_TRY
+#define END_CATCH XEND_CATCH 
 
 #define PTRY XTRY(pool)
-#define PTHROW XTHROW(pool)
+#define PTHROW XTHROW(pool.exception())
 #define PCATCH(e) XCATCH(e)
-#define PINALLY(p) XFINALLY(pool)
-#define PEND_TRY XEND_TRY
+#define PEND_CATCH XEND_CATCH 
 
-#define RTRY XTRY(r.pool())
-#define RTHROW XTHROW(r.pool())
-#define RCATCH(e) XCATCH(e)
-#define RFINALLY(p) XFINALLY(r.pool())
-#define REND_TRY XEND_TRY
+#define RTHROW XTHROW(r.pool().exception())
+//@}
 
 #endif