docs: add dev docs for "getAdjacentFixedPeriods"

doc/usage/get-adjacent-fixed-periods.md

@@ -0,0 +1,137 @@
+# `getAdjacentFixedPeriods`
+
+* [API](#getAdjacentFixedPeriods-api)
+* [Examples](#getAdjacentFixedPeriods-examples)
+
+<a name="getAdjacentFixedPeriods-api"></a>
+## API
+
+### Arguments
+
+| Option | Type | Required | Default value | Description |
+|-|-|-|-|-|
+| `period` | `FixedPeriod` | yes | - | A period id, e.g. `2020` or `2020April` |
+| `calendar` | `SupportedCalendar` | yes | - | A calendar sytem, e.g. `gregory` or `ethiopic` |
+| `steps` | `integer` | no | `1` | Amount of adjacent fixed period forward/backward, can be negative |
+| `locale` | `string` | no | `"en"` | A language locale for the displayed labels |
+
+### Return value
+
+Returns a collection with fixed periods, see `src/period-calculation/types.ts`
+
+<a name="getAdjacentFixedPeriods-examples"></a>
+## Examples
+
+**With `steps: 1` (default):**
+
+```ts
+const period = createFixedPeriodFromPeriodId({
+    periodId: '20230101',
+    calendar: 'gregory',
+})
+getAdjacentFixedPeriods({
+    period,
+    calendar: 'gregory',
+})
+```
+
+will return:
+
+```ts
+{
+    periodType: 'YEARLY',
+    name: '2023',
+    displayName: '2023',
+    id: '2023',
+    iso: '2023',
+    startDate: '2023-01-01',
+    endDate: '2023-12-31',
+}
+```
+
+**With `steps: 2`:**
+
+```ts
+const period = createFixedPeriodFromPeriodId({
+    periodId: '20221230',
+    calendar: 'gregory',
+})
+getAdjacentFixedPeriods({
+    period,
+    calendar: 'gregory',
+    steps: 2,
+})
+```
+
+will return:
+
+```ts
+[
+    {
+        periodType: 'DAILY',
+        name: '2022-12-31',
+        displayName: 'December 31, 2022',
+        id: '20221231',
+        iso: '20221231',
+        startDate: '2022-12-31',
+        endDate: '2022-12-31',
+    },
+    {
+        periodType: 'DAILY',
+        name: '2023-01-01',
+        displayName: 'January 1, 2023',
+        id: '20230101',
+        iso: '20230101',
+        startDate: '2023-01-01',
+        endDate: '2023-01-01',
+    },
+]
+```
+
+**With `steps: -3`:**
+
+```ts
+const period = createFixedPeriodFromPeriodId({
+    periodId: '20230102',
+    calendar: 'gregory',
+})
+getAdjacentFixedPeriods({
+    period,
+    calendar: 'gregory',
+    steps: -3,
+})
+```
+
+will return:
+
+```ts
+[
+    {
+        periodType: 'DAILY',
+        name: '2022-12-30',
+        displayName: 'December 30, 2022',
+        id: '20221230',
+        iso: '20221230',
+        startDate: '2022-12-30',
+        endDate: '2022-12-30',
+    },
+    {
+        periodType: 'DAILY',
+        name: '2022-12-31',
+        displayName: 'December 31, 2022',
+        id: '20221231',
+        iso: '20221231',
+        startDate: '2022-12-31',
+        endDate: '2022-12-31',
+    },
+    {
+        periodType: 'DAILY',
+        name: '2023-01-01',
+        displayName: 'January 1, 2023',
+        id: '20230101',
+        iso: '20230101',
+        startDate: '2023-01-01',
+        endDate: '2023-01-01',
+    },
+]
+```