diff --git a/README.md b/README.md
index c82e9f0c..d84355f0 100644
--- a/README.md
+++ b/README.md
@@ -21,13 +21,15 @@
 
 # CameraKit
 
-CameraKit is an easy to use utility to work with the Android Camera APIs. Everything at the moment is work in progress, but it works well for pictures at least.
+CameraKit is a well documented, high-level library that makes capturing pictures and videos easy, addressing most of the common issues and needs, and still leaving you with flexibility where needed.
 
 <p>
   <img src="art/screen1.png" width="250" vspace="20" hspace="5">
   <img src="art/screen2.png" width="250" vspace="20" hspace="5">
 </p>
 
+Please read the javadocs in code if you have any doubt about the usage of a certain method or feature.
+
 ## Table of Contents
 
 - [Features](#features)
diff --git a/camerakit/src/main/base/com/flurgle/camerakit/CameraOptions.java b/camerakit/src/main/base/com/flurgle/camerakit/CameraOptions.java
index a262edd7..01bb4eb0 100644
--- a/camerakit/src/main/base/com/flurgle/camerakit/CameraOptions.java
+++ b/camerakit/src/main/base/com/flurgle/camerakit/CameraOptions.java
@@ -14,7 +14,6 @@ import java.util.Set;
 /**
  * Options telling you what is available and what is not.
  */
-@SuppressWarnings("deprecation")
 public class CameraOptions {
 
     private Set<Integer> supportedWhiteBalance = new HashSet<>(5);
@@ -27,6 +26,7 @@ public class CameraOptions {
 
 
     // Camera1 constructor.
+    @SuppressWarnings("deprecation")
     CameraOptions(Camera.Parameters params) {
         List<String> strings;
         Mapper mapper = new Mapper.Mapper1();
diff --git a/camerakit/src/main/java/com/flurgle/camerakit/CameraListener.java b/camerakit/src/main/java/com/flurgle/camerakit/CameraListener.java
index 7449325a..4f00f3ed 100644
--- a/camerakit/src/main/java/com/flurgle/camerakit/CameraListener.java
+++ b/camerakit/src/main/java/com/flurgle/camerakit/CameraListener.java
@@ -7,6 +7,7 @@ import java.io.File;
 
 public abstract class CameraListener {
 
+
     /**
      * Notifies that the camera was opened.
      * The {@link CameraOptions} object collects all supported options by the current camera.
@@ -18,16 +19,38 @@ public abstract class CameraListener {
     }
 
 
+    /**
+     * Notifies that the camera session was closed.
+     */
     public void onCameraClosed() {
 
     }
 
 
+    /**
+     * Notifies that a picture previously captured with {@link CameraView#capturePicture()}
+     * or {@link CameraView#captureSnapshot()} is ready to be shown or saved.
+     *
+     * If planning to get a bitmap, you can use {@link CameraUtils#decodeBitmap(byte[], CameraUtils.BitmapCallback)}
+     * to decode the byte array taking care about orientation.
+     *
+     * @param jpeg captured picture
+     */
     public void onPictureTaken(byte[] jpeg) {
 
     }
-    
 
+
+    /**
+     * Notifies that a video capture has just ended. The file parameter is the one that
+     * was passed to {@link CameraView#startCapturingVideo(File)}, if any.
+     * If not, the camera fallsback to:
+     * <code>
+     *     new File(getContext().getExternalFilesDir(null), "video.mp4");
+     * </code>
+     *
+     * @param video file hosting the mp4 video
+     */
     public void onVideoTaken(File video) {
 
     }