Lists.transform() documentation unclear on reversibility

[GoogleCodeExporter]

I believe the javadoc for Lists.transform() to contains a subtly 
misleading statement. It states:

------------------------------------------------------
Returns a list that applies function to each element of fromList. The 
returned list is a transformed view of fromList; changes to fromList will 
be reflected in the returned list and vice versa. 

Since functions are not reversible, the transform is one-way and new items 
cannot be stored in the returned list. The add, addAll and set methods are 
unsupported in the returned list.

....
------------------------------------------------------

The first paragraph says "changes to fromList will be reflected in the 
returned list *and vice versa*". To me "vice-versa" indicates complete and 
symmetric reflection, that any changes in one list will be reflected in 
the other. As the next paragraph makes clear, this is not true for the 
case of changing the contents of the returned list, which cannot be 
reverse-transformed back into the fromList.

I think a clearer description would be to state something like:

------------------------------------------------------
Returns a list that applies function to each element of fromList. The 
returned list is a transformed view of fromList; removing elements from 
the fromList will be reflected in the returned list and vice versa. Any 
other changes to the fromList will be reflected in the returned list, but 
since functions are not reversible, adding or replacing elements on the 
returned list is not supported so the add, addAll and set methods are 
unsupported on the returned list.
------------------------------------------------------

Original issue reported on code.google.com by dov...@gmail.com on 26 Aug 2008 at 5:54

[GoogleCodeExporter]

Thanks for the suggestion, but I prefer the existing phrasing. It resembles the
analogous Javadoc of JDK methods like Map.keySet(), an excellent standard to 
follow:

"Returns a Set view of the keys contained in this map. The set is backed by the 
map,
so changes to the map are reflected in the set, and vice-versa. If the map is
modified while an iteration over the set is in progress (except through the
iterator's own remove operation), the results of the iteration are undefined. 
The set
supports element removal, which removes the corresponding mapping from the map, 
via
the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It 
does
not support the add or addAll operations."

Original comment by jared.l....@gmail.com on 26 Aug 2008 at 7:21

• Changed state: WontFix