Index: trunk/src/org/openstreetmap/josm/data/osm/DataSet.java
===================================================================
--- trunk/src/org/openstreetmap/josm/data/osm/DataSet.java	(revision 3586)
+++ trunk/src/org/openstreetmap/josm/data/osm/DataSet.java	(revision 3588)
@@ -42,4 +42,36 @@
  * Note that DataSet is not an osm-primitive and so has no key association but a few members to
  * store some information.
+ *
+ * Dataset is threadsafe - accessing Dataset simultaneously from different threads should never
+ * lead to data corruption or ConccurentModificationException. However when for example one thread
+ * removes primitive and other thread try to add another primitive reffering to the removed primitive,
+ * DataIntegrityException will occur.
+ *
+ * To prevent such situations, read/write lock is provided. While read lock is used, it's guaranteed that
+ * Dataset will not change. Sample usage:
+ * <code>
+ *   ds.getReadLock().lock();
+ *   try {
+ *     // .. do something with dataset
+ *   } finally {
+ *     ds.getReadLock().unlock();
+ *   }
+ * </code>
+ *
+ * Write lock should be used in case of bulk operations. In addition to ensuring that other threads can't
+ * use dataset in the middle of modifications it also stops sending of dataset events. That's good for performance
+ * reasons - GUI can be updated after all changes are done.
+ * Sample usage:
+ * <code>
+ * ds.beginUpdate()
+ * try {
+ *   // .. do modifications
+ * } finally {
+ *  ds.endUpdate();
+ * }
+ * </code>
+ *
+ * Note that it is not necessary to call beginUpdate/endUpdate for every dataset modification - dataset will get locked
+ * automatically.
  *
  * @author imi