updated documentation

src/main/java/net/engio/mbassy/bus/config/BusConfiguration.java

@@ -78,7 +78,8 @@ public class BusConfiguration implements IBusConfiguration {
      * @return a Default BusConfiguration
      */
     public static BusConfiguration Default(int numberOfDispatchers, int initialCoreThreads, int maximumCoreThreads) {
-    	ThreadPoolExecutor executor = new ThreadPoolExecutor(initialCoreThreads, maximumCoreThreads, 1, TimeUnit.MINUTES, new LinkedBlockingQueue<Runnable>(), AsynchronousHandlerThreadFactory);
+    	ThreadPoolExecutor executor = new ThreadPoolExecutor(initialCoreThreads, maximumCoreThreads, 1,
+                TimeUnit.MINUTES, new LinkedBlockingQueue<Runnable>(), AsynchronousHandlerThreadFactory);
     	return Default(numberOfDispatchers, executor);
     }
     

src/main/java/net/engio/mbassy/listener/Synchronized.java

@@ -4,7 +4,14 @@ import java.lang.annotation.*;
 
 /**
  * A handler marked with this annotation is guaranteed to be invoked in a thread-safe manner, that is, no
- * other running message publication will be able to invoke this handler as long as it has not done its work.
+ * other running message publication will be able to invoke this or any other synchronized handler of the same
+ * listener until the handler completed. It is equal to wrapping the handler code in a synchronized{} block.
+ * This feature will reduce performance of message publication. Try to avoid shared mutable state whenever possible
+ * and use immutable data instead.
+ *
+ * Note: Unsynchronized handlers may still be invoked concurrently with synchronized ones
+ *
+ *
  *
  * @author bennidi
  *         Date: 3/31/13