--- jsr166/src/jsr166y/package-info.java	2008/07/25 18:10:41	1.2
+++ jsr166/src/jsr166y/package-info.java	2009/01/06 14:30:31	1.3
@@ -6,6 +6,24 @@
 
 
 /**
- * Preview versions of classes targeted for Java 7.
+ * Preview versions of classes targeted for Java 7.  Includes a
+ * fine-grained parallel computation framework: ForkJoinTasks and
+ * their related support classes provide a very efficient basis for
+ * obtaining platform-independent parallel speed-ups of
+ * computation-intensive operations.  They are not a full substitute
+ * for the kinds of arbitrary processing supported by Executors or
+ * Threads. However, when applicable, they typically provide
+ * significantly greater performance on multiprocessor platforms.
+ *
+ * <p> Candidates for fork/join processing mainly include those that
+ * can be expressed using parallel divide-and-conquer techniques: To
+ * solve a problem, break it in two (or more) parts, and then solve
+ * those parts in parallel, continuing on in this way until the
+ * problem is too small to be broken up, so is solved directly.  The
+ * underlying <em>work-stealing</em> framework makes subtasks
+ * available to other threads (normally one per CPU), that help
+ * complete the tasks.  In general, the most efficient ForkJoinTasks
+ * are those that directly implement this algorithmic design pattern.
+ *
  */
 package jsr166y;