Skip to content

Commit

Permalink
[brightness] add doc comments in source (expo#13693)
Browse files Browse the repository at this point in the history
  • Loading branch information
Simek authored Jul 21, 2021
1 parent 626fb3e commit a2ea8bc
Show file tree
Hide file tree
Showing 9 changed files with 250 additions and 161 deletions.
6 changes: 5 additions & 1 deletion docs/components/plugins/APISection.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,11 @@ const filterDataByKind = (
? entries.filter((entry: GeneratedData) => entry.kind === kind && additionalCondition(entry))
: [];

const isHook = ({ name }: GeneratedData) => name.startsWith('use');
const isHook = ({ name }: GeneratedData) =>
name.startsWith('use') &&
// note(simek): hardcode this exception until the method will be renamed
name !== 'useSystemBrightnessAsync';

const isListener = ({ name }: GeneratedData) => name.endsWith('Listener');

const renderAPI = (
Expand Down
152 changes: 2 additions & 150 deletions docs/pages/versions/unversioned/sdk/brightness.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Brightness
sourceCodeUrl: 'https://github.com/expo/expo/tree/master/packages/expo-brightness'
---

import APISection from '~/components/plugins/APISection';
import InstallSection from '~/components/plugins/InstallSection';
import PlatformsSection from '~/components/plugins/PlatformsSection';
import SnackInline from '~/components/plugins/SnackInline';
Expand Down Expand Up @@ -63,156 +64,7 @@ const styles = StyleSheet.create({
import * as Brightness from 'expo-brightness';
```

## Methods

### `Brightness.isAvailableAsync()`

Returns whether the Brightness API is enabled on the current device. This does not check the app permissions.

#### Returns

Async `boolean`, indicating whether the Brightness API is available on the current device. Currently this resolves `true` on iOS and Android only.

### `Brightness.requestPermissionsAsync()`

Asks the user to grant permissions for accessing system brightness.

#### Returns

A promise that resolves to an object of type [PermissionResponse](permissions.md#permissionresponse).

### `Brightness.getPermissionsAsync()`

Checks user's permissions for accessing system brightness.

#### Returns

A promise that resolves to an object of type [PermissionResponse](permissions.md#permissionresponse).

### `Brightness.getBrightnessAsync()`

Gets the current brightness level of the device's main screen.

#### Returns

A `Promise` that is resolved with a number between 0 and 1, inclusive, representing the current screen brightness.

---

### `Brightness.setBrightnessAsync(brightnessValue)`

Sets the current screen brightness. On iOS, this setting will persist until the device is locked, after which the screen brightness will revert to the user's default setting. On Android, this setting only applies to the current activity; it will override the system brightness value whenever your app is in the foreground.

#### Arguments

- **brightnessValue (_number_)** - A number between 0 and 1, inclusive, representing the desired screen brightness.

#### Returns

A `Promise` that is resolved when the brightness has been successfully set.

#### Error Codes

- [`ERR_BRIGHTNESS`](#err_brightness)

---

### `Brightness.useSystemBrightnessAsync()`

**Android only.** Resets the brightness setting of the current activity to use the system-wide brightness value rather than overriding it.

#### Returns

A `Promise` that is resolved when the setting has been successfully changed.

---

### `Brightness.isUsingSystemBrightnessAsync()`

**Android only.** Returns a boolean specifying whether or not the current activity is using the system-wide brightness value.

#### Returns

A `Promise` that resolves with `true` when the current activity is using the system-wide brightness value, and `false` otherwise.

#### Error Codes

- [`ERR_BRIGHTNESS`](#err_brightness)

---

### `Brightness.getSystemBrightnessAsync()`

**Android only.** Gets the global system screen brightness.

#### Returns

A `Promise` that is resolved with a number between 0 and 1, inclusive, representing the current system screen brightness.

#### Error Codes

- [`ERR_BRIGHTNESS_SYSTEM`](#err_brightness_system)

---

### `Brightness.setSystemBrightnessAsync(brightnessValue)`

> **WARNING:** This method is experimental.
**Android only.** Sets the global system screen brightness and changes the brightness mode to `MANUAL`. Requires `SYSTEM_BRIGHTNESS` permissions.

#### Arguments

- **brightnessValue (_number_)** - A number between 0 and 1, inclusive, representing the desired screen brightness.

#### Returns

A `Promise` that is resolved when the brightness has been successfully set.

#### Error Codes

- [`ERR_BRIGHTNESS_MODE`](#err_brightness_mode)
- [`ERR_BRIGHTNESS_PERMISSIONS_DENIED`](#err_brightness_permissions_denied)

### `Brightness.getSystemBrightnessModeAsync()`

**Android only.** Gets the system brightness mode (e.g. whether or not the OS will automatically adjust the screen brightness depending on ambient light).

#### Returns

A `Promise` that is resolved with a [`BrightnessMode`](#brightnessbrightnessmode). Requires `SYSTEM_BRIGHTNESS` permissions.

#### Error Codes

- [`ERR_BRIGHTNESS_MODE`](#err_brightness_mode)

---

### `Brightness.setSystemBrightnessModeAsync(brightnessMode)`

**Android only.** Sets the system brightness mode.

#### Arguments

- **brightnessMode (_[BrightnessMode](#brightnessbrightnessmode)_)** - One of `BrightnessMode.MANUAL` or `BrightnessMode.AUTOMATIC`. The system brightness mode cannot be set to `BrightnessMode.UNKNOWN`.

#### Returns

A `Promise` that is resolved when the brightness mode has been successfully set.

#### Error Codes

- [`ERR_INVALID_ARGUMENT`](#err_invalid_argument)
- [`ERR_BRIGHTNESS_MODE`](#err_brightness_mode)
- [`ERR_BRIGHTNESS_PERMISSIONS_DENIED`](#err_brightness_permissions_denied)

## Enum Types

### Brightness.BrightnessMode

- **`BrightnessMode.AUTOMATIC`** - Mode in which the device OS will automatically adjust the screen brightness depending on the ambient light.
- **`BrightnessMode.MANUAL`** - Mode in which the screen brightness will remain constant and will not be adjusted by the OS.
- **`BrightnessMode.UNKNOWN`** - Means that the current brightness mode cannot be determined.
<APISection packageName="expo-brightness" apiName="Brightness" />

## Error Codes

Expand Down
1 change: 1 addition & 0 deletions docs/public/static/data/unversioned/expo-brightness.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"name":"expo-brightness","kind":0,"kindString":"Project","originalName":"","children":[{"name":"BrightnessMode","kind":4,"kindString":"Enumeration","children":[{"name":"AUTOMATIC","kind":16,"kindString":"Enumeration member","comment":{"shortText":"Mode in which the device OS will automatically adjust the screen brightness depending on the\nambient light."},"defaultValue":"1"},{"name":"MANUAL","kind":16,"kindString":"Enumeration member","comment":{"shortText":"Mode in which the screen brightness will remain constant and will not be adjusted by the OS."},"defaultValue":"2"},{"name":"UNKNOWN","kind":16,"kindString":"Enumeration member","comment":{"shortText":"Means that the current brightness mode cannot be determined."},"defaultValue":"0"}]},{"name":"PermissionStatus","kind":4,"kindString":"Enumeration","children":[{"name":"DENIED","kind":16,"kindString":"Enumeration member","defaultValue":"\"denied\""},{"name":"GRANTED","kind":16,"kindString":"Enumeration member","defaultValue":"\"granted\""},{"name":"UNDETERMINED","kind":16,"kindString":"Enumeration member","defaultValue":"\"undetermined\""}]},{"name":"PermissionResponse","kind":256,"kindString":"Interface","children":[{"name":"canAskAgain","kind":1024,"kindString":"Property","type":{"type":"intrinsic","name":"boolean"}},{"name":"expires","kind":1024,"kindString":"Property","type":{"type":"reference","name":"PermissionExpiration"}},{"name":"granted","kind":1024,"kindString":"Property","type":{"type":"intrinsic","name":"boolean"}},{"name":"status","kind":1024,"kindString":"Property","type":{"type":"reference","name":"PermissionStatus"}}]},{"name":"getBrightnessAsync","kind":64,"kindString":"Function","signatures":[{"name":"getBrightnessAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"Gets the current brightness level of the device's main screen.","returns":"A `Promise` that fulfils with a number between `0` and `1`, inclusive, representing the\ncurrent screen brightness.\n"},"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"number"}],"name":"Promise"}}]},{"name":"getPermissionsAsync","kind":64,"kindString":"Function","signatures":[{"name":"getPermissionsAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"Checks user's permissions for accessing system brightness.","returns":"A promise that fulfils with an object of type [PermissionResponse](#permissionrespons).\n"},"type":{"type":"reference","typeArguments":[{"type":"reference","name":"PermissionResponse"}],"name":"Promise"}}]},{"name":"getSystemBrightnessAsync","kind":64,"kindString":"Function","signatures":[{"name":"getSystemBrightnessAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"__Android only.__ Gets the global system screen brightness.","returns":"A `Promise` that is resolved with a number between `0` and `1`, inclusive, representing\nthe current system screen brightness.\n"},"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"number"}],"name":"Promise"}}]},{"name":"getSystemBrightnessModeAsync","kind":64,"kindString":"Function","signatures":[{"name":"getSystemBrightnessModeAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"__Android only.__ Gets the system brightness mode (e.g. whether or not the OS will automatically\nadjust the screen brightness depending on ambient light).","returns":"A `Promise` that fulfils with a [`BrightnessMode`](#brightnessmode). Requires\n`SYSTEM_BRIGHTNESS` permissions.\n"},"type":{"type":"reference","typeArguments":[{"type":"reference","name":"BrightnessMode"}],"name":"Promise"}}]},{"name":"isAvailableAsync","kind":64,"kindString":"Function","signatures":[{"name":"isAvailableAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"Returns whether the Brightness API is enabled on the current device. This does not check the app\npermissions.","returns":"Async `boolean`, indicating whether the Brightness API is available on the current device.\nCurrently this resolves `true` on iOS and Android only.\n"},"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"boolean"}],"name":"Promise"}}]},{"name":"isUsingSystemBrightnessAsync","kind":64,"kindString":"Function","signatures":[{"name":"isUsingSystemBrightnessAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"__Android only.__ Returns a boolean specifying whether or not the current activity is using the\nsystem-wide brightness value.","returns":"A `Promise` that fulfils with `true` when the current activity is using the system-wide\nbrightness value, and `false` otherwise.\n"},"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"boolean"}],"name":"Promise"}}]},{"name":"requestPermissionsAsync","kind":64,"kindString":"Function","signatures":[{"name":"requestPermissionsAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"Asks the user to grant permissions for accessing system brightness.","returns":"A promise that fulfils with an object of type [PermissionResponse](#permissionrespons).\n"},"type":{"type":"reference","typeArguments":[{"type":"reference","name":"PermissionResponse"}],"name":"Promise"}}]},{"name":"setBrightnessAsync","kind":64,"kindString":"Function","signatures":[{"name":"setBrightnessAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"Sets the current screen brightness. On iOS, this setting will persist until the device is locked,\nafter which the screen brightness will revert to the user's default setting. On Android, this\nsetting only applies to the current activity; it will override the system brightness value\nwhenever your app is in the foreground.","returns":"A `Promise` that fulfils when the brightness has been successfully set.\n"},"parameters":[{"name":"brightnessValue","kind":32768,"kindString":"Parameter","comment":{"text":"A number between `0` and `1`, inclusive, representing the desired screen\nbrightness."},"type":{"type":"intrinsic","name":"number"}}],"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"void"}],"name":"Promise"}}]},{"name":"setSystemBrightnessAsync","kind":64,"kindString":"Function","signatures":[{"name":"setSystemBrightnessAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"> __WARNING:__ This method is experimental.","text":"__Android only.__ Sets the global system screen brightness and changes the brightness mode to\n`MANUAL`. Requires `SYSTEM_BRIGHTNESS` permissions.","returns":"A `Promise` that fulfils when the brightness has been successfully set.\n"},"parameters":[{"name":"brightnessValue","kind":32768,"kindString":"Parameter","comment":{"text":"A number between `0` and `1`, inclusive, representing the desired screen\nbrightness."},"type":{"type":"intrinsic","name":"number"}}],"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"void"}],"name":"Promise"}}]},{"name":"setSystemBrightnessModeAsync","kind":64,"kindString":"Function","signatures":[{"name":"setSystemBrightnessModeAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"__Android only.__ Sets the system brightness mode."},"parameters":[{"name":"brightnessMode","kind":32768,"kindString":"Parameter","comment":{"text":"One of `BrightnessMode.MANUAL` or `BrightnessMode.AUTOMATIC`. The system\nbrightness mode cannot be set to `BrightnessMode.UNKNOWN`.\n"},"type":{"type":"reference","name":"BrightnessMode"}}],"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"void"}],"name":"Promise"}}]},{"name":"useSystemBrightnessAsync","kind":64,"kindString":"Function","signatures":[{"name":"useSystemBrightnessAsync","kind":4096,"kindString":"Call signature","comment":{"shortText":"__Android only.__ Resets the brightness setting of the current activity to use the system-wide\nbrightness value rather than overriding it.","returns":"A `Promise` that fulfils when the setting has been successfully changed.\n"},"type":{"type":"reference","typeArguments":[{"type":"intrinsic","name":"void"}],"name":"Promise"}}]}]}
2 changes: 2 additions & 0 deletions packages/expo-brightness/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

### 🛠 Breaking changes

- Rename `useSystemBrightnessAsync` method to `resetToSystemBrightnessAsync` to avoid it being interpreted as a hook. ([#13693](https://github.com/expo/expo/pull/13693) by [@Simek](https://github.com/Simek))

### 🎉 New features

### 🐛 Bug fixes
Expand Down
75 changes: 72 additions & 3 deletions packages/expo-brightness/build/Brightness.d.ts

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit a2ea8bc

Please sign in to comment.