Javadoc cleanup and improvements.

build.xml

@@ -111,11 +111,12 @@
     <javadoc windowtitle="${lib.name} API" doctitle="${lib.name} API"
              overview="${src.dir}/${doc.overview}" destdir="${javadoc.dir}"
              additionalparam="-breakiterator"
-             link="http://samskivert.com/code/samskivert/samskivert/docs/api/">
+             link="http://samskivert.com/code/samskivert/docs/">
       <packageset dir="${src.dir}">
+        <exclude name="com/samskivert/depot/impl/**"/>
+        <exclude name="com/samskivert/depot/tests/**"/>
         <exclude name="com/samskivert/depot/EHCacheAdapter.java" unless="build.ehcache"/>
         <exclude name="com/samskivert/depot/tools/**" unless="build.tools"/>
-        <exclude name="com/samskivert/depot/tests/**" unless="build.tests"/>
       </packageset>
       <bottom>Copyright &#169; 2006-${year} ${copyright.holder}. All Rights Reserved.</bottom>
       <classpath refid="classpath"/>

src/java/com/samskivert/depot/annotation/package-info.java

@@ -0,0 +1,24 @@
+//
+// $Id$
+//
+// Depot library - a Java relational persistence library
+// Copyright (C) 2006-2009 Michael Bayne and Pär Winzell
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+/**
+ * Annotations used on persistent record classes.
+ */
+package com.samskivert.depot.annotation;

src/java/com/samskivert/depot/clause/package-info.java

@@ -0,0 +1,24 @@
+//
+// $Id$
+//
+// Depot library - a Java relational persistence library
+// Copyright (C) 2006-2009 Michael Bayne and Pär Winzell
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+/**
+ * Models the clauses of a SQL query: where, join, limit, etc.
+ */
+package com.samskivert.depot.clause;

src/java/com/samskivert/depot/expression/ColumnExp.java

@@ -30,7 +30,8 @@ import com.samskivert.depot.impl.operator.IsNull;
 import com.samskivert.depot.impl.operator.Like;
 
 /**
- * An expression that unambiguously identifies a field of a class, e.g. GameRecord.itemId.
+ * An expression that unambiguously identifies a field of a class, for example
+ * <code>GameRecord.itemId</code>.
  */
 public class ColumnExp extends FluentExp
 {

src/java/com/samskivert/depot/expression/FluentExp.java

@@ -35,8 +35,7 @@ import com.samskivert.depot.impl.operator.NotEquals;
 import com.samskivert.depot.impl.operator.Sub;
 
 /**
- * A base class for {@link SQLExpression} implementations that provides a plethora of combinators
- * for composing expressions.
+ * Provides a fluent API for creating most SQL expressions like and, or, equal, not equal, etc.
  */
 public abstract class FluentExp
     implements SQLExpression
@@ -113,85 +112,85 @@ public abstract class FluentExp
         return new LessThanEquals(this, expr);
     }
 
-    /** Returns an {@link And} with this expression and the supplied target. */
+    /** Returns a boolean and of this expression and the supplied target. */
     public FluentExp and (SQLExpression expr)
     {
         return Ops.and(this, expr);
     }
 
-    /** Returns an {@link Or} with this expression and the supplied target. */
+    /** Returns a boolean or of this expression and the supplied target. */
     public FluentExp or (SQLExpression expr)
     {
         return Ops.or(this, expr);
     }
 
-    /** Returns an {@link BitAnd} with this expression and the supplied target. */
+    /** Returns a bitwise and of this expression and the supplied target. */
     public FluentExp bitAnd (Comparable<?> value)
     {
         return new BitAnd(this, value);
     }
 
-    /** Returns an {@link BitAnd} with this expression and the supplied target. */
+    /** Returns a bitwise and of this expression and the supplied target. */
     public FluentExp bitAnd (SQLExpression expr)
     {
         return new BitAnd(this, expr);
     }
 
-    /** Returns an {@link BitOr} with this expression and the supplied target. */
+    /** Returns a bitwise or of this expression and the supplied target. */
     public FluentExp bitOr (Comparable<?> value)
     {
         return new BitOr(this, value);
     }
 
-    /** Returns an {@link BitOr} with this expression and the supplied target. */
+    /** Returns a bitwise or of this expression and the supplied target. */
     public FluentExp bitOr (SQLExpression expr)
     {
         return new BitOr(this, expr);
     }
 
-    /** Returns an {@link Add} with this expression and the supplied target. */
+    /** Returns the sum of this expression and the supplied target. */
     public FluentExp plus (Comparable<?> value)
     {
         return new Add(this, value);
     }
 
-    /** Returns an {@link Add} with this expression and the supplied target. */
+    /** Returns the sum of this expression and the supplied target. */
     public FluentExp plus (SQLExpression expr)
     {
         return new Add(this, expr);
     }
 
-    /** Returns a {@link Sub} with this expression and the supplied target. */
+    /** Returns this expression minus the supplied target. */
     public FluentExp minus (Comparable<?> value)
     {
         return new Sub(this, value);
     }
 
-    /** Returns a {@link Sub} with this expression and the supplied target. */
+    /** Returns this expression minus the supplied target. */
     public FluentExp minus (SQLExpression expr)
     {
         return new Sub(this, expr);
     }
 
-    /** Returns a {@link Mul} with this expression and the supplied target. */
+    /** Returns this expression times the supplied target. */
     public FluentExp times (Comparable<?> value)
     {
         return new Mul(this, value);
     }
 
-    /** Returns a {@link Mul} with this expression and the supplied target. */
+    /** Returns this expression times the supplied target. */
     public FluentExp times (SQLExpression expr)
     {
         return new Mul(this, expr);
     }
 
-    /** Returns a {@link Div} with this expression and the supplied target. */
+    /** Returns this expression divided by the supplied target. */
     public FluentExp div (Comparable<?> value)
     {
         return new Div(this, value);
     }
 
-    /** Returns a {@link Div} with this expression and the supplied target. */
+    /** Returns this expression divided by the supplied target. */
     public FluentExp div (SQLExpression expr)
     {
         return new Div(this, expr);

src/java/com/samskivert/depot/expression/SQLExpression.java

@@ -31,6 +31,7 @@ import com.samskivert.depot.impl.SQLBuilder;
  */
 public interface SQLExpression
 {
+    /** Used internally to represent the lack of a value. */
     public static final class NoValue
     {
         public NoValue (String reason)

src/java/com/samskivert/depot/expression/package-info.java

@@ -0,0 +1,24 @@
+//
+// $Id$
+//
+// Depot library - a Java relational persistence library
+// Copyright (C) 2006-2009 Michael Bayne and Pär Winzell
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+/**
+ * Contains the API by which SQL expressions are created.
+ */
+package com.samskivert.depot.expression;

src/java/com/samskivert/depot/operator/package-info.java

@@ -0,0 +1,24 @@
+//
+// $Id$
+//
+// Depot library - a Java relational persistence library
+// Copyright (C) 2006-2009 Michael Bayne and Pär Winzell
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+/**
+ * Operators that cannot be created via the fluent API.
+ */
+package com.samskivert.depot.operator;

src/java/com/samskivert/depot/package-info.java

@@ -0,0 +1,24 @@
+//
+// $Id$
+//
+// Depot library - a Java relational persistence library
+// Copyright (C) 2006-2009 Michael Bayne and Pär Winzell
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+/**
+ * The bulk of the Depot public API.
+ */
+package com.samskivert.depot;

src/java/com/samskivert/depot/tools/package-info.java

@@ -0,0 +1,24 @@
+//
+// $Id$
+//
+// Depot library - a Java relational persistence library
+// Copyright (C) 2006-2009 Michael Bayne and Pär Winzell
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+/**
+ * Build tools, specifically the genrecord Ant task.
+ */
+package com.samskivert.depot.tools;

src/java/com/samskivert/depot/util/package-info.java

@@ -0,0 +1,24 @@
+//
+// $Id$
+//
+// Depot library - a Java relational persistence library
+// Copyright (C) 2006-2009 Michael Bayne and Pär Winzell
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+/**
+ * Various utilities.
+ */
+package com.samskivert.depot.util;