From df9106dac903cbdca51d19fc1767c5ae734c1787 Mon Sep 17 00:00:00 2001 From: gimy Date: Wed, 4 Oct 2023 10:03:40 +0800 Subject: [PATCH] docs: preparing for the api doc page --- docs/api.md | 20 ++++++++++++++- docs/guide/one-time-calculator.md | 2 +- docs/guide/reactive-calculator.md | 4 +-- docs/roadmap.md | 1 + src/types/CalculationsConfig.ts | 42 +++++++++++++++---------------- 5 files changed, 44 insertions(+), 25 deletions(-) diff --git a/docs/api.md b/docs/api.md index a2abefd..4798b91 100644 --- a/docs/api.md +++ b/docs/api.md @@ -9,10 +9,28 @@ - [Constructor](#ReactiveCalculator-Constructor) - [Methods](#ReactiveCalculator-Methods) - [Helper Functions](#Helper-Functions) - - [calculateQibla](#calculateQibla) + - [calculateQiblaDirection](#calculateQiblaDirection) + - [recommendMethod](#recommendMethod) - [Types](#Types) + - [AsrTime](#AsrTime) + - [CustomMethod](#CustomMethod) + - [CalculationConfig](#CalculationConfig) + - [ReactiveCalculationConfig](#ReactiveCalculationConfig) - [CoordinatesObject](#CoordinatesObject) + - [FormatterConfig](#FormatterConfig) + - [HijriCalendar](#HijriCalendar) + - [Iqama](#Iqama) + - [Method](#Method) + - [PrayerAdjustments](#PrayerAdjustments) + - [PrayerNamesType](#PrayerNamesType) + - [PrayerNames](#PrayerNames) + - [TimesNamesType](#TimesNamesType) + - [TimesNames](#TimesNames) + - [EventType](#EventType) + - [PrayersTimeObject](#PrayersTimeObject) + - [FormattedTimeObject](#FormattedTimeObject) - [TimeObject](#TimeObject) + - [TimeEventObject](#TimeEventObject) --- diff --git a/docs/guide/one-time-calculator.md b/docs/guide/one-time-calculator.md index 6ef1854..edbd3a3 100644 --- a/docs/guide/one-time-calculator.md +++ b/docs/guide/one-time-calculator.md @@ -78,7 +78,7 @@ calculator.getAllPrayerTimes() // check the output tab ### `getPrayerTime` -Returns the time for a specific prayer based on the initialized date. Accepts a prayer parameter of type [`PrayerNames`](). +Returns the time for a specific prayer based on the initialized date. Accepts a prayer parameter of type `PrayerNamesType`. Use the [`PrayerNames`]() enum for available prayer names. ```ts import { Methods, PrayerNames, StaticCalculator } from 'prayer-call' diff --git a/docs/guide/reactive-calculator.md b/docs/guide/reactive-calculator.md index 30d7645..ec19c04 100644 --- a/docs/guide/reactive-calculator.md +++ b/docs/guide/reactive-calculator.md @@ -78,7 +78,7 @@ reactiveCalculator.getAllPrayerTimes() // check the output tab ### `getPrayerTime` -`getPrayerTime` returns a Javascript `Date` object with the name and Adhan time of the specified prayer. Accepts a prayer parameter of type [`PrayerNames`](). +`getPrayerTime` returns a Javascript `Date` object with the name and Adhan time of the specified prayer. Accepts prayer parameter of type `PrayerNamesType`. Use the [`PrayerNames`]() enum for available prayer names. ```ts import { Methods, ReactiveCalculator, PrayerNames } from 'prayer-call' @@ -99,7 +99,7 @@ reactiveCalculator.getPrayerTime(PrayerNames.FAJR) Returns a [`TimeObject`]() representing the time of the middle and the last third of the night respectively based on the moon. Useful for Qiyam calculations. ```ts -import { Methods, ReactiveCalculator, PrayerNames } from 'prayer-call' +import { Methods, ReactiveCalculator } from 'prayer-call' // calculations for Cyberjaya const reactiveCalculator = new ReactiveCalculator({ diff --git a/docs/roadmap.md b/docs/roadmap.md index 277e928..4974896 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,6 +1,7 @@ - Write more tests to cover the library - Offer open source tools to make comparing and building calculation methods easier. - Re-write the library from scratch making it reactive from the ground up (using vue 3 reactive core api) +- Do we need to have daylight saving times handled in the library? if yes what's the best way to do it? - improve the docs to have examples imported from actual ts files - translated the docs to Arabic - Add altitude to the calculation formula diff --git a/src/types/CalculationsConfig.ts b/src/types/CalculationsConfig.ts index e710f75..096760f 100644 --- a/src/types/CalculationsConfig.ts +++ b/src/types/CalculationsConfig.ts @@ -7,31 +7,30 @@ import type { ValueOf } from './TypesUtils' import type { HijriCalendar } from './HijriCalendar' // TODO: add a configuration to take into consideration the altitude of the location -// TODO: add a configuration to take into consideration daylight savings -// TODO: add a configuration to take into consideration ramadan timings (+30min on top of the 90min used for UmmAlQura) +// TODO: add a configuration to take into consideration daylight savings time export interface CustomMethod { /** - * Angle of the sun used to calculate Fajr + * Angle of the sun, in degrees, used to calculate Fajr * @defaultValue 18 * */ fajrAngle?: number /** - * Angle of the sun used to calculate Isha + * Angle of the sun, in degrees used to calculate Isha * @defaultValue 18 * */ ishaAngle?: number /** - * Minutes after Maghrib (if set, the time for Isha will be Maghrib plus ishaInterval) + * Minutes after Maghrib (if set, ishaAngle would be ignored and the time for Isha will be Maghrib plus ishaInterval) * @defaultValue 0 * */ ishaInterval?: number /** - * Angle of the sun used to calculate Maghrib + * Angle of the sun, in degrees used to calculate Maghrib. only used by Tehran method * @defaultValue 0 * */ maghribAngle?: number /** - * Object with custom prayer time adjustments (in minutes) specifically for the method for each prayer time + * Custom adjustments, in minutes, for each prayer time specific to the method. * @defaultValue { fajr: 0, sunrise: 0, dhuhr: 0, asr: 0, maghrib: 0, isha: 0 } * */ methodAdjustments?: Partial @@ -39,62 +38,63 @@ export interface CustomMethod { export interface CalculationsConfig { /** - * the starting date for the calculations (can use past and future dates) + * The starting date for the calculations, in the local time zone. Can use past, current, or future dates. * @defaultValue new Date() * */ date: Date /** - * latitude of the location + * Latitude of the location, in degrees. Range: -90 to 90. * */ latitude: number /** - * longitude of the location + * Longitude of the location, in degrees. Range: -180 to 180. * */ longitude: number /** - * method used for the calculation + * Method used for the calculation, see [Calculation methods](https://prayers-ts.netlify.app/config/methods.html) * @defaultValue Methods.UMM_AL_QURA * */ method?: Methods | CustomMethod /** - * Object with custom prayer time adjustments (in minutes) for each prayer time + * Custom adjustments, in minutes, for each prayer time. * @defaultValue { fajr: 0, sunrise: 0, dhuhr: 0, asr: 0, maghrib: 0, isha: 0 } * */ adjustments?: Partial /** - * Value from the HighLatitudeRule object, used to set a minimum time for Fajr and a max time for Isha + * Rule to use for calculating prayer times at high latitudes. + * see [Advanced config](https://prayers-ts.netlify.app/config/config.html#advanced-configuration) * @defaultValue HighLatitudeRule.MiddleOfTheNight * */ highLatitudeRule?: ValueOf /** - * Earlier (Jumhoor) or later (Hanafi) Asr time calculation + * Whether to use the earlier (Jumhoor) or later (Hanafi) Asr time calculation. * @defaultValue AsrTime.JUMHOOR * */ asrTime?: AsrTime /** - * handle the particular cases of Midnight Sun & Polar Night days - * see: https://github.com/batoulapps/adhan-js/pull/30 + * How to handle Midnight Sun & Polar Night days. + * see [Advanced config](https://prayers-ts.netlify.app/config/config.html#advanced-configuration) * @defaultValue PolarCircleResolution.Unresolved * */ polarCircleResolution?: ValueOf /** - * Object with waiting time (minutes) for iqama after the actual prayer time + * Waiting time, in minutes, for iqama after the actual prayer time. * @defaultValue { fajr: 20, dhuhr: 10, asr: 10, maghrib: 5, isha: 15 } * */ iqama?: Partial /** - * if set to true will adjust the prayer times for Ramadan by adding 30 minutes to Isha - * This is usually practiced in umm al-qura method + * Whether to adjust the prayer times for Ramadan by adding 30 minutes to Isha. + * Done by default for Umm Al-Qura method * @defaultValue false */ adjustForRamadan?: boolean /** - * what hijri calendar to use for the calculation + * Hijri calendar to use in conjunction with adjustments for Ramadan to determine the first and last day of Ramadan. * @defaultValue HijriCalendar.UMM_AL_QURA */ hijriCalendar?: HijriCalendar /** - * if set to true will output logs that can be helpful for debugging + * If set to true will output logs that can be helpful for debugging * @defaultValue false */ debug?: boolean