Added migration guide for v3, tweak docs, add changelog.

CHANGELOG.md

@@ -1,7 +1,11 @@
 # ChangeLog
 
-- 3.0.0 2017/05/01
-  - Add 
+- 3.0.0 2017/09/16
+  - Add fully [Kotlin support](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/kotlin_support.md)!
+  - Allow for Deterministic, Reproducible Builds with sorted inputs [#342](https://github.com/permissions-dispatcher/PermissionsDispatcher/pull/342)
+  - Internal: Migrate Lint Rules to UAST [363](https://github.com/permissions-dispatcher/PermissionsDispatcher/pull/363)
+  - Rename withCheck to withPermissionCheck [#365](https://github.com/permissions-dispatcher/PermissionsDispatcher/pull/365)
+  - Fix CallNeedsPermissionDetector to work correctly [#368](https://github.com/permissions-dispatcher/PermissionsDispatcher/pull/368)
 - 2.4.0 2017/05/01
   - Fix `SupportV13MissingException` with newer Gradle [#279](https://github.com/hotchemi/PermissionsDispatcher/issues/279).
     - Now we bundle support v13 library in the library, you don't have to add v13 dependency by yourself.

README.md

@@ -2,18 +2,20 @@
 
 ![image](https://raw.githubusercontent.com/hotchemi/PermissionsDispatcher/master/doc/logo.png)
 
-- **100% reflection-free**
+- [**Fully Kotlin support**](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/kotlin_support.md)
 - [**Special Permissions support**](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/special_permissions.md)
 - **Xiaomi support**
-- [**Fully Kotlin support**](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/kotlin_support.md)
+- **100% reflection-free**
 
-PermissionsDispatcher provides a simple annotation-based API to handle runtime permissions in Android Marshmallow.
+PermissionsDispatcher provides a simple annotation-based API to handle runtime permissions.
 
 This library lifts the burden that comes with writing a bunch of check statements whether a permission has been granted or not from you, in order to keep your code clean and safe.
 
 ## Usage
 
-Here's a minimum example, in which we register a `MainActivity` which requires `Manifest.permission.CAMERA`.
+- If you're using Kotlin check [**Kotlin ver**](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/kotlin_support.md) first of all.
+
+Here's a minimum example, in which you register a `MainActivity` which requires `Manifest.permission.CAMERA`.
 
 ### 0. Prepare AndroidManifest
 
@@ -100,23 +102,22 @@ Check out the [sample](https://github.com/hotchemi/PermissionsDispatcher/tree/ma
 - [Getting Special Permissions](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/special_permissions.md)
 - [maxSdkVersion](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/maxsdkversion.md)
 - Xiaomi
-  - Since Xiaomi manipulates something around runtime permission mechanism Google's recommended way [doesn't work well](https://github.com/hotchemi/PermissionsDispatcher/issues/187).
-But don't worry, PermissionsDispatcher supports it! Check related [PR](https://github.com/hotchemi/PermissionsDispatcher/issues/187) for more detail.
+  - Since Xiaomi manipulates something around runtime permission mechanism Google's recommended way [doesn't work well](https://github.com/hotchemi/PermissionsDispatcher/issues/187). But don't worry, PermissionsDispatcher supports it! Check related [PR](https://github.com/hotchemi/PermissionsDispatcher/issues/187) for more detail.
 - [IntelliJ plugin](https://github.com/shiraji/permissions-dispatcher-plugin)
 - AndroidAnnotations plugin
   - If you use [AndroidAnnotations](http://androidannotations.org/), you need to add [AndroidAnnotationsPermissionsDispatcherPlugin](https://github.com/AleksanderMielczarek/AndroidAnnotationsPermissionsDispatcherPlugin).
 
 ### Known issues
 
-If you're in trouble before filing an issue check known issues [list](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/known_issues.md).
+If you're in trouble check known issues [list](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/known_issues.md) before filing an issue.
 
 ### Users
 
 Thankfully we've got hundreds of [users](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/users.md) around the world!
 
 ## Download
 
-To add it to your project, include the following in your **app module** `build.gradle` file:
+To add PermissionsDispatcher to your project, include the following in your **app module** `build.gradle` file:
 
 `${latest.version}` is [![Download](https://api.bintray.com/packages/hotchemi/maven/permissionsdispatcher/images/download.svg)](https://bintray.com/hotchemi/maven/permissionsdispatcher/_latestVersion)
 
@@ -140,7 +141,11 @@ repositories {
 }
 ```
 
-If you're in trouble and use Jitpack check this [doc](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/jitpack.md).
+### Misc
+
+- If you include [Jitpack.io](https://jitpack.io/) dependencies in your project, it is important to review the order of the repositories available to your app module
+  - Because of the library's artifact ID, Jitpack might be tempted to resolve the dependency on its own, which could lead to an error during Gradle's configuration time
+- If you're going to bump up the major version number we recommend to refer our [migration guide](https://github.com/hotchemi/PermissionsDispatcher/blob/master/doc/kotlin_support.md) 
 
 ## Licence
 

doc/known_issues.md

@@ -1,3 +1,5 @@
+## Known Issues
+
 If you are in trouble, you might get the solution from these issues.
 
 - [Asking for permission in onResume might cause infinite loop](https://github.com/hotchemi/PermissionsDispatcher/issues/90)

doc/kotlin_support.md

@@ -1,4 +1,4 @@
-### Fully Kotlin support(experimental)
+## Fully Kotlin support(experimental)
 
 From 3.0.0 we started support `.kt` file generation.
 
@@ -18,27 +18,26 @@ Add the following line to `AndroidManifest.xml`:
 @RuntimePermissions
 class MainActivity : AppCompatActivity(), View.OnClickListener {
 
-    // now you can use internal!
     @NeedsPermission(Manifest.permission.CAMERA)
-    internal fun showCamera() {
+    fun showCamera() {
         supportFragmentManager.beginTransaction()
                 .replace(R.id.sample_content_fragment, CameraPreviewFragment.newInstance())
                 .addToBackStack("camera")
                 .commitAllowingStateLoss()
     }
 
     @OnShowRationale(Manifest.permission.CAMERA)
-    internal fun showRationaleForCamera(request: PermissionRequest) {
+    fun showRationaleForCamera(request: PermissionRequest) {
         showRationaleDialog(R.string.permission_camera_rationale, request)
     }
 
     @OnPermissionDenied(Manifest.permission.CAMERA)
-    internal fun onCameraDenied() {
+    fun onCameraDenied() {
         Toast.makeText(this, R.string.permission_camera_denied, Toast.LENGTH_SHORT).show()
     }
 
     @OnNeverAskAgain(Manifest.permission.CAMERA)
-    internal fun onCameraNeverAskAgain() {
+    fun onCameraNeverAskAgain() {
         Toast.makeText(this, R.string.permission_camera_never_askagain, Toast.LENGTH_SHORT).show()
     }
 }

doc/migration_guide.md

@@ -1,4 +1,55 @@
-## Migrating to PermissionsDispatcher 2.x
+# Migration guide
+
+- [Migrating to 3.x](#migration-3)
+- [Migrating to 2.x](#migration-2)
+
+## Migrating to PermissionsDispatcher 3.x <a id="migration-3"></a>
+
+### Method name changing
+
+Issue: https://github.com/permissions-dispatcher/PermissionsDispatcher/issues/355
+
+From 1.0 PermissionsDispatcher has been generating `***WithCheck` method, but from 3.0 the suffix of each method becomes `***WithPermissionCheck`.
+
+```diff
+- MainActivityPermissionsDispatcher.showCameraWithCheck(this);
++ MainActivityPermissionsDispatcher.showCameraWithPermissionCheck(this);
+```
+
+The motivation of this change is to make generated code more declarative and easy to figure out what'd be going on under the hood.
+
+Especially the change is beneficial in Kotlin because the receiver of generated method is a class which is annotated with `@RuntimePermissions`, not a helper class named as `XXXPermissionsDispatcher`.
+
+### Kotlin support
+
+Issue: https://github.com/permissions-dispatcher/PermissionsDispatcher/issues/320
+
+Actually it's been possible to use PermissionsDispatcher with Kotlin because of its interoperability with Java. But to give you more concise and comfortable experience we added fully Kotlin support which is described in [here](https://github.com/permissions-dispatcher/PermissionsDispatcher/blob/master/doc/kotlin_support.md).
+
+If you're already using PermissionsDispatcher with Kotlin, be aware of the following 2 changing points.
+
+#### `WithPermissionsCheck`
+
+```diff
+button.setOnClickListener {
+-    MainActivityPermissionsDispatcher.showCameraWithCheck(this)
++    showCameraWithPermissionCheck()
+}
+```
+
+#### `onRequestPermissionsResult`
+
+```diff
+override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
+    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
+-    MainActivityPermissionsDispatcher.onRequestPermissionsResult(requestCode, grantResults)
++    onRequestPermissionsResult(requestCode, grantResults)
+}
+```
+
+And that's it!
+
+## Migrating to PermissionsDispatcher 2.x <a id="migration-2"></a>
 
 Since the internals of PermissionsDispatcher 2 have undergone a fundamental refactoring, most notably in the switch of languages to Kotlin for our annotation processor, the exposed APIs to users of the library have been tweaked as well. This guide will help you migrate to the latest version in just a few minutes!
 
@@ -36,15 +87,13 @@ While version 1.x of the library had two flavors of the `@NeedsPermission` annot
 ```java
 @NeedsPermissions({ CAMERA, WRITE_EXTERNAL_STORAGE })
 void setupCamera() {
-	// ...
 }
 ```
 
 #### After
 ```java
 @NeedsPermission({ CAMERA, WRITE_EXTERNAL_STORAGE })
 void setupCamera() {
-	// ...
 }
 ```
 
@@ -56,21 +105,21 @@ Both `@ShowsRationale` and its plural form `@ShowsRationales` have been removed
 ```java
 @ShowsRationale({ CAMERA, WRITE_EXTERNAL_STORAGE })
 void showCameraRationale() {
-	// Can't really do much here, since the system dialog is shown immediately afterwards...
-	Toast.makeText(...).show();
+    // Can't really do much here, since the system dialog is shown immediately afterwards...
+    Toast.makeText(...).show();
 }
 ```
 
 #### After
 ```java
 @OnShowRationale({ CAMERA, WRITE_EXTERNAL_STORAGE })
 void showCameraRationale(final PermissionRequest request) {
-	// E.g. show a dialog explaining why you need the permission.
-	// Call proceed() or cancel() on the incoming request to continue or abort the current permissions process
-	new AlertDialog.Builder(...)
-		.setPositiveButton("OK", (dialog, which) -> request.proceed())
-		.setNegativeButton("Abort", (dialog, which) -> request.cancel())
-		.show();
+    // E.g. show a dialog explaining why you need the permission.
+    // Call proceed() or cancel() on the incoming request to continue or abort the current permissions process
+    new AlertDialog.Builder(...)
+        .setPositiveButton("OK", (dialog, which) -> request.proceed())
+        .setNegativeButton("Abort", (dialog, which) -> request.cancel())
+        .show();
 }
 ```
 
@@ -82,15 +131,13 @@ The old annotations `@DeniedPermission` and `@DeniedPermissions` have been unifi
 ```java
 @DeniedPermission({ CAMERA, WRITE_EXTERNAL_STORAGE })
 void cameraDenied() {
-	// ...
 }
 ```
 
 #### After
 ```java
 @OnPermissionDenied({ CAMERA, WRITE_EXTERNAL_STORAGE })
 void cameraDenied() {
-	// ...
 }
 ```
 

doc/users.md

@@ -1,3 +1,5 @@
+## Users
+
 More detail, please check [appbrain](http://www.appbrain.com/stats/libraries/details/permissions_dispatcher/permissionsdispatcher).
 
 - [Airbnb](https://play.google.com/store/apps/details?id=com.airbnb.android)