Skip to content

Commit

Permalink
Review and revise documentation
Browse files Browse the repository at this point in the history 
* Add missing @param and @returns where found.
* Type returns on methods.
* Conform to some sort of style.
  • Loading branch information
@takameyer
takameyer committed Jul 12, 2023
1 parent e1a87a9 commit 170ac54
Show file tree
Hide file tree
Showing 26 changed files with 566 additions and 465 deletions.
4 changes: 1 addition & 3 deletions packages/realm/src/ClassHelpers.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,7 @@ import {

type ObjectWrapper = (obj: binding.Obj) => (RealmObject & DefaultObject) | null;

/**
* @internal
*/
/** @internal */
export type ClassHelpers = {
constructor: RealmObjectConstructor;
objectSchema: binding.ObjectSchema;
Expand Down
6 changes: 2 additions & 4 deletions packages/realm/src/ClassMap.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,7 @@ import {
setClassHelpers,
} from "./internal";

/**
* @internal
*/
/** @internal */
export class ClassMap {
private mapping: Record<string, Constructor<unknown>>;
private nameByTableKey: Record<binding.TableKey, string>;
Expand Down Expand Up @@ -129,7 +127,7 @@ export class ClassMap {
properties,
wrapObject(obj) {
if (obj.isValid) {
return RealmObject.createWrapper(realm, obj, constructor);
return RealmObject.createWrapper(obj, constructor);
} else {
return null;
}
Expand Down
16 changes: 8 additions & 8 deletions packages/realm/src/Collection.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,21 +60,21 @@ export abstract class Collection<

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all keys in the collection
* @returns An iterator with all keys in the collection.
* @since 0.11.0
*/
abstract keys(): Iterable<KeyType>;

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all values in the collection
* @returns An iterator with all values in the collection.
* @since 0.11.0
*/
abstract values(): Iterable<ValueType>;

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.keys}
* @returns Iterator with all key/value pairs in the collection
* @returns An iterator with all key/value pairs in the collection.
* @since 0.11.0
*/
abstract entries(): Iterable<EntryType>;
Expand All @@ -88,7 +88,7 @@ export abstract class Collection<
* spread operators, and more.
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator Symbol.iterator}
* and the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable iterable protocol}
* @returns Iterable of each value in the collection
* @returns An iterable of each value in the collection.
* @example
* for (let object of collection) {
* // do something with each object
Expand All @@ -106,15 +106,15 @@ export abstract class Collection<

/**
* Add a listener `callback` which will be called when a **live** collection instance changes.
* @param callback A function to be called when changes occur.
* @param callback - A function to be called when changes occur.
* The callback function is called with two arguments:
* - `collection`: the collection instance that changed,
* - `changes`: a dictionary with keys `insertions`, `newModifications`, `oldModifications`
* and `deletions`, each containing a list of indices in the collection that were
* inserted, updated or deleted respectively. `deletions` and `oldModifications` are
* indices into the collection before the change happened, while `insertions` and
* `newModifications` are indices into the new version of the collection.
* @throws a {@link TypeAssertionError} If `callback` is not a function.
* @throws A {@link TypeAssertionError} if `callback` is not a function.
* @example
* wines.addListener((collection, changes) => {
* // collection === wines
Expand All @@ -134,8 +134,8 @@ export abstract class Collection<

/**
* Remove the listener `callback` from the collection instance.
* @param callback Callback function that was previously
* added as a listener through the **addListener** method.
* @param callback - Callback function that was previously
* added as a listener through the {@link Collection.addListener} method.
* @throws a {@link TypeAssertionError} If `callback` is not a function.
*/
removeListener(callback: ChangeCallbackType): void {
Expand Down
122 changes: 1 addition & 121 deletions packages/realm/src/Configuration.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ export type BaseConfiguration = {
readOnly?: boolean;
fifoFilesFallbackPath?: string;
sync?: SyncConfiguration;
/**@internal */ openSyncedRealmLocally?: true;
/** @internal */ openSyncedRealmLocally?: true;
shouldCompact?: (totalBytes: number, usedBytes: number) => boolean;
deleteRealmIfMigrationNeeded?: boolean;
disableFormatUpgrade?: boolean;
Expand All @@ -59,126 +59,6 @@ export type ConfigurationWithoutSync = BaseConfiguration & {

export type Configuration = ConfigurationWithSync | ConfigurationWithoutSync;

// export type PartitionValue = string | number | null | ObjectId | UUID;

// /**
// * A function which can be called to migrate a Realm from one version of the schema to another.
// */
// export type MigrationCallback = (oldRealm: Realm, newRealm: Realm) => void;

// export enum ClientResetModeManualOnly {
// Manual = "manual",
// }

// export enum ClientResetMode {
// Manual = "manual",
// DiscardLocal = "discardLocal",
// }

// export type ClientResetBeforeCallback = (localRealm: Realm) => void;
// export type ClientResetAfterCallback = (localRealm: Realm, remoteRealm: Realm) => void;
// export type ClientResetConfiguration<ClientResetModeT = ClientResetMode> = {
// mode: ClientResetModeT;
// clientResetBefore?: ClientResetBeforeCallback;
// clientResetAfter?: ClientResetAfterCallback;
// };

// export type BaseSyncConfiguration = {
// user: User;
// customHttpHeaders?: { [header: string]: string };
// ssl?: SSLConfiguration;
// _sessionStopPolicy?: SessionStopPolicy;
// newRealmFileBehavior?: OpenRealmBehaviorConfiguration;
// existingRealmFileBehavior?: OpenRealmBehaviorConfiguration;
// error?: ErrorCallback;
// };

// // We only allow `flexible` to be `true` or `undefined` - `{ flexible: false }`
// // is not allowed. This is because TypeScript cannot discriminate that
// // type correctly with `strictNullChecks` disabled, and there's no real use
// // case for `{ flexible: false }`.
// export type FlexibleSyncConfiguration = BaseSyncConfiguration & {
// flexible: true;
// partitionValue?: never;
// clientReset?: ClientResetConfiguration<ClientResetModeManualOnly>;
// /**
// * Optional object to configure the setup of an initial set of flexible
// * sync subscriptions to be used when opening the Realm. If this is specified,
// * {@link Realm.open} will not resolve until this set of subscriptions has been
// * fully synchronized with the server.
// *
// * Example:
// * ```
// * const config: Configuration = {
// * sync: {
// * user,
// * flexible: true,
// * initialSubscriptions: {
// * update: (subs, realm) => {
// * subs.add(realm.objects('Task'));
// * },
// * rerunOnOpen: true,
// * },
// * },
// * // ... rest of config ...
// * };
// * const realm = await Realm.open(config);
// *
// * // At this point, the Realm will be open with the data for the initial set
// * // subscriptions fully synchronised.
// * ```
// */
// initialSubscriptions?: {
// /**
// * Callback called with the {@link Realm} instance to allow you to setup the
// * initial set of subscriptions by calling `realm.subscriptions.update`.
// * See {@link SubscriptionSet.update} for more information.
// */
// update: (subs: MutableSubscriptionSet, realm: Realm) => void;
// /**
// * If `true`, the {@link update} callback will be rerun every time the Realm is
// * opened (e.g. every time a user opens your app), otherwise (by default) it
// * will only be run if the Realm does not yet exist.
// */
// rerunOnOpen?: boolean;
// };
// };

// export type PartitionSyncConfiguration = BaseSyncConfiguration & {
// flexible?: never;
// partitionValue: PartitionValue;
// clientReset?: ClientResetConfiguration<ClientResetMode>;
// };

// export type SyncConfiguration = FlexibleSyncConfiguration | PartitionSyncConfiguration;

// export type BaseConfiguration = {
// encryptionKey?: ArrayBuffer | ArrayBufferView | Int8Array;
// schema?: (ObjectConstructor | ObjectSchema)[];
// schemaVersion?: number;
// shouldCompactOnLaunch?: (totalBytes: number, usedBytes: number) => boolean;
// onFirstOpen?: (realm: Realm) => void;
// path?: string;
// fifoFilesFallbackPath?: string;
// readOnly?: boolean;
// };

// export type ConfigurationWithSync = BaseConfiguration & {
// sync: SyncConfiguration;
// migration?: never;
// inMemory?: never;
// deleteRealmIfMigrationNeeded?: never;
// disableFormatUpgrade?: never;
// };

// export type ConfigurationWithoutSync = BaseConfiguration & {
// sync?: never;
// migration?: MigrationCallback;
// inMemory?: boolean;
// deleteRealmIfMigrationNeeded?: boolean;
// disableFormatUpgrade?: boolean;
// };

/**
* Validate the fields of a user-provided Realm configuration.
* @internal
Expand Down
32 changes: 17 additions & 15 deletions packages/realm/src/Dictionary.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,21 +178,23 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
*/
private declare [INTERNAL]: binding.Dictionary;

/**
* @internal
*/
/** @internal */
private declare [HELPERS]: TypeHelpers;

/** @ts-expect-error We're exposing methods in the end-users namespace of keys */
[key: string]: T;

*[Symbol.iterator]() {
/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.entries}
* @returns An iterator with all entries in the dictionary.
*/
*[Symbol.iterator](): Generator<[string, T]> {
yield* this.entries();
}

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all values in the dictionary
* @returns An iterator with all values in the dictionary.
* @since 0.11.0
* @ts-expect-error We're exposing methods in the end-users namespace of keys */
*keys() {
Expand All @@ -206,11 +208,11 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
}

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys Array.prototype.keys}
* @returns Iterator with all values in the dictionary
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values Array.prototype.values}
* @returns An iterator with all values in the dictionary.
* @since 0.11.0
* @ts-expect-error We're exposing methods in the end-users namespace of keys */
*values() {
* @ts-expect-error We're exposing methods in the end-users namespace of values */
*values(): Generator<T> {
const { fromBinding } = this[HELPERS];
const snapshot = this[INTERNAL].values.snapshot();
const size = snapshot.size();
Expand All @@ -221,11 +223,11 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
}

/**
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.keys}
* @returns Iterator with all key/value pairs in the dictionary
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries Array.prototype.entries}
* @returns An iterator with all key/value pairs in the dictionary.
* @since 0.11.0
* @ts-expect-error We're exposing methods in the end-users namespace of keys */
*entries() {
* @ts-expect-error We're exposing methods in the end-users namespace of entries */
*entries(): Generator<[string, T]> {
const { fromBinding } = this[HELPERS];
const keys = this[INTERNAL].keys.snapshot();
const values = this[INTERNAL].values.snapshot();
Expand Down Expand Up @@ -267,7 +269,7 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
/**
* Adds one or more elements with the specified key and value to the dictionary or updates value if key exists.
* @param elementsOrKey The element to add or the key of the element to add.
* @param value The value of the element to add.
* @param value - The value of the element to add.
* @throws an {@link AssertionError} If not inside a write transaction, if using symbol as keys, or if any value violates type constraints.
* @returns The dictionary.
* @since 10.6.0
Expand All @@ -288,7 +290,7 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
/**
* Removes elements from the dictionary, with the keys provided.
* This does not throw if the keys are already missing from the dictionary.
* @param key The key to be removed.
* @param key - The key to be removed.
* @throws an {@link AssertionError} If not inside a write transaction.
* @returns The dictionary
* @since 10.6.0
Expand Down
4 changes: 2 additions & 2 deletions packages/realm/src/GeoSpatial.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ const earthRadiusMi = 3963.16760121; //earthRadiusKm / 1.609344 (km/mi)

/**
* Converts the input kilometer value in radians.
* @param km The kilometers to convert.
* @param km - The kilometers to convert.
* @returns The corresponding number of radians.
*/
export function kmToRadians(km: number): number {
Expand All @@ -181,7 +181,7 @@ export function kmToRadians(km: number): number {

/**
* Converts the input miles value in radians.
* @param mi The miles to convert.
* @param mi - The miles to convert.
* @returns The corresponding number of radians.
*/
export function miToRadians(mi: number): number {
Expand Down

0 comments on commit 170ac54

Please sign in to comment.