app/permission: add documentation and storage permissions

Storage permissions enables the Android permissions
READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE.

app/doc.go

@@ -67,35 +67,7 @@ Permissions
 
 The packages under gioui.org/app/permission should be imported
 by a Gio program or by one of its dependencies to indicate that specific
-operating-system permissions are required. For example, if a Gio
-program requires access to a device's Bluetooth interface, it
-should import "gioui.org/app/permission/bluetooth" as follows:
-
-	package main
-
-	import (
-		"gioui.org/app"
-		_ "gioui.org/app/permission/bluetooth"
-	)
-
-	func main() {
-		...
-	}
-
-Since there are no exported identifiers in the app/permission/bluetooth
-package, the import uses the anonymous identifier (_) as the imported
-package name.
-
-As a special case, the gogio tool detects when a program directly or
-indirectly depends on the "net" package from the Go standard library as an
-indication that the program requires network access permissions. If a program
-requires network permissions but does not directly or indirectly import
-"net", it will be necessary to add the following code somewhere in the
-program's source code:
-
-	import (
-		...
-		_ "net"
-	)
+operating-system permissions are required.  Please see documentation for
+package gioui.org/app/permission for more information.
 */
 package app

app/permission/bluetooth/main.go

@@ -1 +1,24 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+/*
+Package bluetooth implements permissions to access Bluetooth and Bluetooth
+Low Energy hardware, including the ability to discover and pair devices.
+
+Android
+
+The following entries will be added to AndroidManifest.xml:
+
+    <uses-permission android:name="android.permission.BLUETOOTH"/>
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
+    <uses-feature android:name="android.hardware.bluetooth" android:required="false"/>
+    <uses-feature android:name="android.hardware.bluetooth_le" android:required="false"/>
+
+Note that ACCESS_FINE_LOCATION is required on Android before the Bluetooth
+device may be used.
+See https://developer.android.com/guide/topics/connectivity/bluetooth.
+
+ACCESS_FINE_LOCATION is a "dangerous" permission. See documentation for
+package gioui.org/app/permission for more information.
+*/
 package bluetooth

app/permission/bluetooth_le/main.go

@@ -1 +0,0 @@
-package bluetooth_le

app/permission/doc.go

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+/*
+Package permission includes sub-packages that should be imported
+by a Gio program or by one of its dependencies to indicate that specific
+operating-system permissions are required. For example, if a Gio
+program requires access to a device's Bluetooth interface, it
+should import "gioui.org/app/permission/bluetooth" as follows:
+
+	package main
+
+	import (
+		"gioui.org/app"
+		_ "gioui.org/app/permission/bluetooth"
+	)
+
+	func main() {
+		...
+	}
+
+Since there are no exported identifiers in the app/permission/bluetooth
+package, the import uses the anonymous identifier (_) as the imported
+package name.
+
+As a special case, the gogio tool detects when a program directly or
+indirectly depends on the "net" package from the Go standard library as an
+indication that the program requires network access permissions. If a program
+requires network permissions but does not directly or indirectly import
+"net", it will be necessary to add the following code somewhere in the
+program's source code:
+
+	import (
+		...
+		_ "net"
+	)
+
+Android -- Dangerous Permissions
+
+Certain permissions on Android are marked with a protection level of
+"dangerous". This means that, in addition to including the relevant Gio
+permission packages, your app will need to prompt the user specifically
+to request access. This can be done with a java Fragment, installed using
+(*app.Window).RegisterFragment(). For more information on dangerous
+permissions, see: https://developer.android.com/guide/topics/permissions/overview#dangerous_permissions
+*/
+package permission

app/permission/storage/main.go

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+/*
+Package storage implements read and write storage permissions
+on mobile devices.
+
+Android
+
+The following entries will be added to AndroidManifest.xml:
+
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
+
+READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE are "dangerous" permissions.
+See documentation for package gioui.org/app/permission for more information.
+*/
+package storage

cmd/gogio/permission.go

@@ -9,15 +9,16 @@ var AndroidPermissions = map[string][]string{
 		"android.permission.BLUETOOTH_ADMIN",
 		"android.permission.ACCESS_FINE_LOCATION",
 	},
-	"bluetooth_le": {
-		"android.permission.BLUETOOTH",
-		"android.permission.BLUETOOTH_ADMIN",
-		"android.permission.ACCESS_FINE_LOCATION",
+	"storage": {
+		"android.permission.READ_EXTERNAL_STORAGE",
+		"android.permission.WRITE_EXTERNAL_STORAGE",
 	},
 }
 
 var AndroidFeatures = map[string][]string{
-	"default":      {`glEsVersion="0x00030000"`},
-	"bluetooth":    {`name="android.hardware.bluetooth"`},
-	"bluetooth_le": {`name="android.hardware.bluetooth_le"`},
+	"default": {`glEsVersion="0x00030000"`},
+	"bluetooth": {
+		`name="android.hardware.bluetooth"`,
+		`name="android.hardware.bluetooth_le"`,
+	},
 }