/*
 * LensKit, an open source recommender systems toolkit.
 * Copyright 2010-2013 Regents of the University of Minnesota and contributors
 * Work on LensKit has been funded by the National Science Foundation under
 * grants IIS 05-34939, 08-08692, 08-12148, and 10-17697.
 *
 * This program 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 program 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 General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program; if not, write to the Free Software Foundation, Inc., 51
 * Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
/**
 * Sparse vectors (both sparse and dense) and their operations.
 *
 * <h2>Sparse Vectors</h2>
 * This package provides a sparse vector
 * framework for storing things such as rating vectors. Sparse vectors are
 * stored efficiently and have a key domain fixed at create time. Storage is
 * linear in the size of the key domain. See
 * {@link org.grouplens.lenskit.vectors.SparseVector} for more details.
 *
 * <p>
 * To allow the type system to communicate valuable information about how
 * vectors are used while still preserving efficiency, sparse vectors come in
 * three forms: <em>read-only</em>, realized by
 * {@link org.grouplens.lenskit.vectors.SparseVector}, provides the basic sparse
 * vector interface; <em>read-write</em>, in
 * {@link org.grouplens.lenskit.vectors.MutableSparseVector}, provides an
 * interface where the values can be changed (e.g. for in-place addition or
 * subtraction); and <em>immutable</em>, in
 * {@link org.grouplens.lenskit.vectors.ImmutableSparseVector}, where the vector
 * is guaranteed to be unchanging and can be safely stored or shared across
 * threads without concern about the caller mutating it later.
 *
 * <p>
 * The {@link org.grouplens.lenskit.vectors.SparseVector SparseVector} class
 * also provides utility methods for manipulating sparse vectors (e.g. the
 * {@link org.grouplens.lenskit.vectors.SparseVector#immutable()
 * SparseVector.immutable()} method for getting an immutable sparse vector).
 *
 * <h2>Vectors</h2>
 * In addition to sparse vectors, this package provides 0-indexed vectors ({@link Vector}
 * and its subclasses), providing efficient linear algebra operations over vectors.
 */
package org.grouplens.lenskit.vectors;

@@ -1005,24 +1005,17 @@
 %0A/**%0A * 
-Sparse v
+V
 ectors (
@@ -1062,142 +1062,172 @@
 ons.
-%0A *%0A * %3Ch2%3ESparse Vectors%3C/h2%3E%0A * This package provides a sparse vector%0A * framework for s
+  This package provides various%0A * vector utilities used by LensKit.%0A *%0A * %3Cp%3EThere are two types of vec
 tor
+s 
 in
-g
  thi
-ngs such as rating vectors. S
+s package: vectors (%7B@link Vector%7D) and s
 parse
+%0A *
  vec
@@ -1235,378 +1235,321 @@
 ors 
-are%0A * stored efficiently and have a key domain fixed at create time. Storage is%0A * linear in the size of the key domain. See%0A * %7B@link org.grouplens.lenskit.vectors.
+(%7B@link SparseVector%7D).  Vectors are the standard linear algebra vectors, with%0A * a particular dimension %5C(d%5C) and elements indexed by integers in the range %5C(%5B0,d)%5C).%0A * 
 Sparse
-V
+ v
 ector
-%7D for more details.%0A *%0A * %3Cp%3E%0A * To allow the type system to communicate valuable information about how%0A * vectors are used while still preserving efficiency, sparse
+s map arbitrary long keys to values sparsely and efficiently.  The keys can%0A * be negative.%0A *%0A * %3Cp%3EEach
  vector
-s
  come
+s
  in
-%0A *
  three f
 orms
@@ -1548,18 +1548,16 @@
 ee f
+lav
 or
-m
 s: 
-%3Cem%3E
 read
@@ -1565,214 +1565,120 @@
 only
-%3C/em%3E, realized by%0A * %7B@link org.grouplens.lenskit.vectors.SparseVector%7D, provides the basic sparse%0A * vector interface; %3Cem%3Eread-write%3C/em%3E, in%0A * %7B@link org.grouplens.lenskit.vectors.MutableSparseVector%7D,
+ (%7B@link Vector%7D and %7B@link SparseVector%7D);%0A * this type is the base of the remaining types for each vector, and
  pro
@@ -1684,17 +1684,26 @@
 ovides a
-n
+ read-only
 %0A * inte
@@ -1712,834 +1712,509 @@
 ace 
-where
+to
  the v
-alues can be changed (e.g. for in-place addition or%0A * subtraction); and %3Cem%3Eimmutable%3C/em%3E, in%0A * %7B@link org.grouplens.lenskit.vectors.ImmutableSparseVector%7D, where the vector%0A * is guaranteed to be unchanging and can be safely stored or shared across%0A * threads without concern about the caller
+ector.  Immutable vectors (%7B@link ImmutableVector%7D%0A * and %7B@link ImmutableSparseVector%7D) are immutable and cannot be%0A * changed once created.  They can also be freely shared between threads.  Finally,
  muta
-ting it later.%0A *%0A * %3Cp%3E%0A * The %7B@link org.grouplens.lenskit.vectors.SparseVector SparseVector%7D class%0A * also provides utility methods for manipulating sparse vectors (e.g. the%0A * %7B@link org.grouplens.lenskit.vectors.SparseVector#immutable()%0A * SparseVector.immutable()%7D method for getting an immutable sparse vector).%0A *%0A * %3Ch2%3EVectors%3C/h2%3E%0A * In addition to sparse vectors, this package provides 0-indexed vectors (%7B@link Vector%7D%0A * and its subclasses), providing efficient linear algebra operations over vectors
+ble vectors%0A * (%7B@link MutableVector%7D) and %7B@link MutableSparseVector%7D)%0A * are mutable and not thread-safe.%0A *%0A * %3Cp%3EThis allows read-only operations to be performed on any type of vector, while allowing%0A * components to specifically work with and store vectors guaranteed to be immutable
 .%0A *

Clean up vector package JavaDoc