add main api godoc comment

config.go

@@ -27,32 +27,151 @@ const (
 )
 
 type ObjectPoolConfig struct {
-	// whether the pool has LIFO (last in, first out)
-	Lifo     bool
+	/**
+	 * Whether the pool has LIFO (last in, first out) behaviour with
+	 * respect to idle objects - always returning the most recently used object
+	 * from the pool, or as a FIFO (first in, first out) queue, where the pool
+	 * always returns the oldest object in the idle object pool.
+	 */
+	Lifo bool
+
+	/**
+	 * The cap on the number of objects that can be allocated by the pool
+	 * (checked out to clients, or idle awaiting checkout) at a given time. Use
+	 * a negative value for no limit.
+	 */
 	MaxTotal int
-	MaxIdle  int
-	MinIdle  int
-	//TODO support fairness config
-	//Fairness                       bool
-	MaxWaitMillis                  int64
-	MinEvictableIdleTimeMillis     int64
-	SoftMinEvictableIdleTimeMillis int64
 
-	NumTestsPerEvictionRun int
+	/**
+	 * The cap on the number of "idle" instances in the pool. Use a
+	 * negative value to indicate an unlimited number of idle instances.
+	 * If MaxIdle
+	 * is set too low on heavily loaded systems it is possible you will see
+	 * objects being destroyed and almost immediately new objects being created.
+	 * This is a result of the active threads momentarily returning objects
+	 * faster than they are requesting them them, causing the number of idle
+	 * objects to rise above maxIdle. The best value for maxIdle for heavily
+	 * loaded system will vary but the default is a good starting point.
+	 */
+	MaxIdle int
 
-	EvictionPolicyName string
+	/**
+	 * The minimum number of idle objects to maintain in
+	 * the pool. This setting only has an effect if it is positive and
+	 * TimeBetweenEvictionRunsMillis is greater than zero. If this
+	 * is the case, an attempt is made to ensure that the pool has the required
+	 * minimum number of instances during idle object eviction runs.
+	 *
+	 * If the configured value of MinIdle is greater than the configured value
+	 * for MaxIdle then the value of MaxIdle will be used instead.
+	 *
+	 */
+	MinIdle int
 
+	/**
+	* Whether objects created for the pool will be validated before
+	* being returned from the <code>ObjectPool.BorrowObject()</code> method. Validation is
+	* performed by the <code>ValidateObject()</code> method of the factory
+	* associated with the pool. If the object fails to validate, then
+	* <code>ObjectPool.BorrowObject()</code> will fail.
+	 */
 	TestOnCreate bool
 
+	/**
+	 * Whether objects borrowed from the pool will be validated before
+	 * being returned from the <code>ObjectPool.BorrowObject()</code> method. Validation is
+	 * performed by the <code>ValidateObject()</code> method of the factory
+	 * associated with the pool. If the object fails to validate, it will be
+	 * removed from the pool and destroyed, and a new attempt will be made to
+	 * borrow an object from the pool.
+	 */
 	TestOnBorrow bool
 
+	/**
+	 * Whether objects borrowed from the pool will be validated when
+	 * they are returned to the pool via the <code>ObjectPool.ReturnObject()</code> method.
+	 * Validation is performed by the <code>ValidateObject()</code> method of
+	 * the factory associated with the pool. Returning objects that fail validation
+	 * are destroyed rather then being returned the pool.
+	 */
 	TestOnReturn bool
 
+	/**
+	* Whether objects sitting idle in the pool will be validated by the
+	* idle object evictor (if any - see
+	*  TimeBetweenEvictionRunsMillis ). Validation is performed
+	* by the <code>ValidateObject()</code> method of the factory associated
+	* with the pool. If the object fails to validate, it will be removed from
+	* the pool and destroyed.  Note that setting this property has no effect
+	* unless the idle object evictor is enabled by setting
+	* TimeBetweenEvictionRunsMillis  to a positive value.
+	 */
 	TestWhileIdle bool
 
-	TimeBetweenEvictionRunsMillis int64
-
+	/**
+	* Whether to block when the <code>ObjectPool.BorrowObject()</code> method is
+	* invoked when the pool is exhausted (the maximum number of "active"
+	* objects has been reached).
+	 */
 	BlockWhenExhausted bool
+
+	//TODO support fairness config
+	//Fairness                       bool
+
+	/**
+	 * The maximum amount of time (in milliseconds) the
+	 * <code>ObjectPool.BorrowObject()</code> method should block before return
+	 * a error when the pool is exhausted and
+	 *  BlockWhenExhausted is true. When less than 0, the
+	 * <code>ObjectPool.BorrowObject()</code> method may block indefinitely.
+	 *
+	 */
+	MaxWaitMillis int64
+
+	/**
+	 * The minimum amount of time an object may sit idle in the pool
+	 * before it is eligible for eviction by the idle object evictor (if any -
+	 * see TimeBetweenEvictionRunsMillis . When non-positive,
+	 * no objects will be evicted from the pool due to idle time alone.
+	 */
+	MinEvictableIdleTimeMillis int64
+
+	/**
+	 * The minimum amount of time an object may sit idle in the pool
+	 * before it is eligible for eviction by the idle object evictor (if any -
+	 * see TimeBetweenEvictionRunsMillis ),
+	 * with the extra condition that at least <code>MinIdle</code> object
+	 * instances remain in the pool. This setting is overridden by
+	 *  MinEvictableIdleTimeMillis (that is, if
+	 *  MinEvictableIdleTimeMillis is positive, then
+	 *  SoftMinEvictableIdleTimeMillis is ignored).
+	 */
+	SoftMinEvictableIdleTimeMillis int64
+
+	/**
+	 * The maximum number of objects to examine during each run (if any)
+	 * of the idle object evictor thread. When positive, the number of tests
+	 * performed for a run will be the minimum of the configured value and the
+	 * number of idle instances in the pool. When negative, the number of tests
+	 * performed will be <code>math.Ceil(ObjectPool.GetNumIdle()/math.
+	 * Abs(PoolConfig.NumTestsPerEvictionRun))</code> which means that when the
+	 * value is <code>-n</code> roughly one nth of the idle objects will be
+	 * tested per run.
+	 */
+	NumTestsPerEvictionRun int
+
+	/**
+	 * The name of the EvictionPolicy implementation that is
+	 * used by this pool. Please register policy by <code>RegistryEvictionPolicy(name, policy)</code>
+	 */
+	EvictionPolicyName string
+
+	/**
+	* The number of milliseconds to sleep between runs of the idle
+	* object evictor thread. When non-positive, no idle object evictor thread
+	* will be run.
+	 */
+	TimeBetweenEvictionRunsMillis int64
 }
 
 func NewDefaultPoolConfig() *ObjectPoolConfig {

factory.go

@@ -3,14 +3,43 @@ package pool
 import "errors"
 
 type PooledObjectFactory interface {
+
+	/**
+	 * Create an instance that can be served by the pool and wrap it in a
+	 * PooledObject to be managed by the pool.
+	 *
+	 * return error if there is a problem creating a new instance,
+	 *    this will be propagated to the code requesting an object.
+	 */
 	MakeObject() (*PooledObject, error)
 
+	/**
+	 * Destroys an instance no longer needed by the pool.
+	 */
 	DestroyObject(object *PooledObject) error
 
+	/**
+	 * Ensures that the instance is safe to be returned by the pool.
+	 *
+	 * return <code>false</code> if <code>object</code> is not valid and should
+	 *         be dropped from the pool, <code>true</code> otherwise.
+	 */
 	ValidateObject(object *PooledObject) bool
 
+	/**
+	 * Reinitialize an instance to be returned by the pool.
+	 *
+	 * return error if there is a problem activating <code>object</code>,
+	 *    this error may be swallowed by the pool.
+	 */
 	ActivateObject(object *PooledObject) error
 
+	/**
+	 * Uninitialize an instance to be returned to the idle object pool.
+	 *
+	 * return error if there is a problem passivating <code>obj</code>,
+	 *    this exception may be swallowed by the pool.
+	 */
 	PassivateObject(object *PooledObject) error
 }
 

pool.go

@@ -69,6 +69,12 @@ func NewObjectPoolWithDefaultConfig(factory PooledObjectFactory) *ObjectPool {
 	return NewObjectPool(factory, NewDefaultPoolConfig())
 }
 
+/**
+ * Create an object using the PooledObjectFactory factory, passivate it, and then place it in
+ * the idle object pool. <code>AddObject</code> is useful for "pre-loading"
+ * a pool with idle objects. (Optional operation).
+ *
+ */
 func (this *ObjectPool) AddObject() error {
 	if this.IsClosed() {
 		return NewIllegalStatusErr("Pool not open")
@@ -91,14 +97,34 @@ func (this *ObjectPool) addIdleObject(p *PooledObject) {
 	}
 }
 
+/**
+* Obtains an instance from this pool.
+*
+* Instances returned from this method will have been either newly created
+* with PooledObjectFactory.MakeObject or will be a previously
+* idle object and have been activated with
+*  PooledObjectFactory.ActivateObject and then validated with
+*  PooledObjectFactory.ValidateObject.
+*
+* By contract, clients <strong>must</strong> return the borrowed instance
+* using <code>ReturnObject</code>, <code>InvalidateObject</code>
+ */
 func (this *ObjectPool) BorrowObject() (interface{}, error) {
 	return this.borrowObject(this.Config.MaxWaitMillis)
 }
 
+/**
+* Return the number of instances currently idle in this pool. This may be
+* considered an approximation of the number of objects that can be
+* BorrowObject borrowed without creating any new instances.
+ */
 func (this *ObjectPool) GetNumIdle() int {
 	return this.idleObjects.Size()
 }
 
+/**
+ * Return the number of instances currently borrowed from this pool.
+ */
 func (this *ObjectPool) GetNumActive() int {
 	return this.allObjects.Size() - this.idleObjects.Size()
 }
@@ -332,6 +358,10 @@ func (this *ObjectPool) IsClosed() bool {
 	return this.closed
 }
 
+/**
+* Return an instance to the pool. By contract, <code>object</code>
+* <strong>must</strong> have been obtained using <code>BorrowObject()</code>
+ */
 func (this *ObjectPool) ReturnObject(object interface{}) error {
 	if debug_pool {
 		fmt.Printf("pool ReturnObject %v \n", object)
@@ -406,6 +436,11 @@ func (this *ObjectPool) ReturnObject(object interface{}) error {
 	return nil
 }
 
+/**
+ * Clears any objects sitting idle in the pool, releasing any associated
+ * resources (optional operation). Idle objects cleared must be
+ *  PooledObjectFactory.DestroyObject(PooledObject) .
+ */
 func (this *ObjectPool) Clear() {
 	p, ok := this.idleObjects.Poll().(*PooledObject)
 
@@ -415,6 +450,15 @@ func (this *ObjectPool) Clear() {
 	}
 }
 
+/**
+* Invalidates an object from the pool.
+*
+* By contract, <code>object</code> <strong>must</strong> have been obtained
+* using BorrowObject.
+* <p>
+* This method should be used when an object that has been borrowed is
+* determined (due to an exception or other problem) to be invalid.
+ */
 func (this *ObjectPool) InvalidateObject(object interface{}) error {
 	p, ok := this.allObjects.Get(object).(*PooledObject)
 	if !ok {
@@ -434,6 +478,9 @@ func (this *ObjectPool) InvalidateObject(object interface{}) error {
 	return nil
 }
 
+/**
+ * Close this pool, and free any resources associated with it.
+ */
 func (this *ObjectPool) Close() {
 	if this.IsClosed() {
 		return