Add clear deprecation path from factory builder method. (#327)

Author: Mike Davis

core-api/src/main/java/com/optimizely/ab/Optimizely.java

@@ -967,6 +967,22 @@ public <T> int addNotificationHandler(Class<T> clazz, NotificationHandler<T> han
     }
 
     //======== Builder ========//
+
+    /**
+     * This overloaded factory method is deprecated in favor of pure builder methods.
+     * Please use {@link com.optimizely.ab.Optimizely#builder()} along with
+     * {@link Builder#withDatafile(java.lang.String)} and
+     * {@link Builder#withEventHandler(com.optimizely.ab.event.EventHandler)}
+     * respectively.
+     *
+     * Example:
+     * <pre>
+     *     Optimizely optimizely = Optimizely.builder()
+     *         .withDatafile(datafile)
+     *         .withEventHandler(eventHandler)
+     *         .build();
+     * </pre>
+     */
     @Deprecated
     public static Builder builder(@Nonnull String datafile,
                                   @Nonnull EventHandler eventHandler) {
@@ -1054,12 +1070,12 @@ public Builder withNotificationCenter(NotificationCenter notificationCenter) {
             return this;
         }
 
-        // Helper function for making testing easier
-        protected Builder withDatafile(String datafile) {
+        public Builder withDatafile(String datafile) {
             this.datafile = datafile;
             return this;
         }
 
+        // Helper functions for making testing easier
         protected Builder withBucketing(Bucketer bucketer) {
             this.bucketer = bucketer;
             return this;