[WIP!] Use jsdoc for embedded documentation on typedefs

Author: kugtong33

index.d.ts

@@ -17,61 +17,86 @@ export interface SnapshotOptions {
 	id?: string;
 }
 
-// When an assert fail, the message string will be shown in the error
 export interface Assertions {
-	// Assert that actual is deep equal to expected
+	/** Assert that `actual` is deep equal to `expected` */
 	deepEqual<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
-	// Failing assertion
+
+	/** Cause the test to fail */
 	fail(message?: string): void;
-	// Assert that actual is equal to false
+
+	/** Assert that `actual` is equal to false */
 	false(actual: any, message?: string): void;
-	// Assert that actual is falsy (false, 0, '', "", null, undefined, NaN)
+
+	/** Assert that `actual` is falsy (false, 0, '', null, undefined, NaN) */
 	falsy(actual: any, message?: string): void;
-	// Assert that error is falsy
+
+	/** Assert that `error` is falsy */
 	ifError(error: any, message?: string): void;
-	// Assert that actual is equal to expected (use deepEqual for objects/arrays)
+
+	/** Assert that `actual` is strictly equal to `expected` */
 	is<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
-	// Assert that actual is not equal to expected (use notDeepEqual for objects/arrays)
+
+	/** Assert that `actual` is not strictly equal to `expected` */
 	not<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
-	// Assert that actual is not deep equal to expected
+
+	/** Assert that `actual` is not deep equal to `expected` */
 	notDeepEqual<ValueType = any>(actual: ValueType, expected: ValueType, message?: string): void;
-	// Assert that string does not follow the regex pattern
+
+	/** Assert that `string` does not match the regex pattern */
 	notRegex(string: string, regex: RegExp, message?: string): void;
-	// Assert that a function that never returns does not throw an error
+
+	/** Assert that a function does not throw */
 	notThrows(value: () => never, message?: string): void;
-	// Assert that a function that returns an observable does not throw an error
+
+	/** Assert that a function that returns an observable does not throw */
 	notThrows(value: () => ObservableLike, message?: string): Promise<void>;
-	// Assert that a function that returns a promise does not throw an error
+
+	/** Assert that a function that returns a promise throws an error */
 	notThrows(value: () => PromiseLike<any>, message?: string): Promise<void>;
-	// Assert that a function that returns any value does not throw an error
+
+	/** Assert that a function does not throw */
 	notThrows(value: () => any, message?: string): void;
-	// Assert that an observable does not throw an error
+
+	/** Assert that an observable does not throw */
 	notThrows(value: ObservableLike, message?: string): Promise<void>;
-	// Assert that a promise does not throw an error
+
+	/** Assert that a promise does not throw */
 	notThrows(value: PromiseLike<any>, message?: string): Promise<void>;
-	// Passing assertion
+
+	/** Passing assertion */
 	pass(message?: string): void;
-	// Assert that string follows the regex pattern
+
+	/** Assert that string match the regex pattern */
 	regex(string: string, regex: RegExp, message?: string): void;
-	// Assert that expected matches a snapshot
+
+	/** Assert that expected matches a snapshot */
 	snapshot(expected: any, message?: string): void;
-	// Assert that expected matches a snapshot with option `id`
+
+	/** Assert that expected matches a snapshot with option `id` */
 	snapshot(expected: any, options: SnapshotOptions, message?: string): void;
-	// Assert that a function that never returns throws an error
+
+	/** Assert that a function that returns any value throws an error */
 	throws(value: () => never, error?: ThrowsErrorValidator, message?: string): any;
-	// Assert that a function that returns an observable throws an error
+
+	/** Assert that a function that returns an observable throws an error */
 	throws(value: () => ObservableLike, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that a function that returns a promise throws an error
+
+	/** Assert that a function that returns a promise throws an error */
 	throws(value: () => PromiseLike<any>, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that a function that returns any value throws an error
+
+	/** Assert that a function that returns any value throws an error */
 	throws(value: () => any, error?: ThrowsErrorValidator, message?: string): any;
-	// Assert that an observable throws an error
+
+	/** Assert that an observable throws an error */
 	throws(value: ObservableLike, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that a promise throws an error
+
+	/** Assert that a promise throws an error */
 	throws(value: PromiseLike<any>, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that actual is equal to true
+
+	/** Assert that actual is equal to true */
 	true(actual: any, message?: string): void;
-	// Assert that actual is truthy ('0', 'false', [], {}, function() {}, etc.)
+
+	/** Assert that actual is truthy ('0', 'false', [], {}, function() {}, etc.) */
 	truthy(actual: any, message?: string): void;
 }
 

index.js.flow

@@ -22,57 +22,80 @@ export interface SnapshotOptions {
 	id?: string;
 }
 
-// When an assert fail, the message string will be shown in the error
 export interface Assertions {
-	// Assert that actual is deep equal to expected
+	/** Assert that `actual` is deep equal to `expected` */
 	deepEqual(actual: any, expected: any, message?: string): void;
-	// Failing assertion
+
+	/** Cause the test to fail */
 	fail(message?: string): void;
-	// Assert that actual is equal to false
+
+	/** Assert that `actual` is equal to false */
 	false(actual: any, message?: string): void;
-	// Assert that actual is falsy (false, 0, '', "", null, undefined, NaN)
+
+	/** Assert that `actual` is falsy (false, 0, '', null, undefined, NaN) */
 	falsy(actual: any, message?: string): void;
-	// Assert that error is falsy
+
+	/** Assert that `error` is falsy */
 	ifError(error: any, message?: string): void;
-	// Assert that actual is equal to expected (use deepEqual for objects/arrays)
+
+	/** Assert that `actual` is strictly equal to `expected` */
 	is(actual: any, expected: any, message?: string): void;
-	// Assert that actual is not equal to expected (use notDeepEqual for objects/arrays)
+
+	/** Assert that `actual` is not strictly equal to `expected` */
 	not(actual: any, expected: any, message?: string): void;
-	// Assert that actual is not deep equal to expected
+
+	/** Assert that `actual` is not deep equal to `expected` */
 	notDeepEqual(actual: any, expected: any, message?: string): void;
-	// Assert that string does not follow the regex pattern
+
+	/** Assert that `string` does not match the regex pattern */
 	notRegex(string: string, regex: RegExp, message?: string): void;
-	// Assert that a function that returns an observable does not throw an error
+
+	/** Assert that a function that returns an observable does not throw */
 	notThrows(value: () => ObservableLike, message?: string): Promise<void>;
-	// Assert that a function that returns a promise does not throw an error
+
+	/** Assert that a function that returns a promise does not throw */
 	notThrows(value: () => PromiseLike<any>, message?: string): Promise<void>;
-	// Assert that a function that returns any value does not throw an error
+
+	/** Assert that a function does not throw */
 	notThrows(value: () => any, message?: string): void;
-	// Assert that an observable does not throw an error
+
+	/** Assert that an observable does not throw */
 	notThrows(value: ObservableLike, message?: string): Promise<void>;
-	// Assert that a promise does not throw an error
+
+	/** Assert that a promise does not throw */
 	notThrows(value: PromiseLike<any>, message?: string): Promise<void>;
-	// Passing assertion
+
+	/** Passing assertion */
 	pass(message?: string): void;
-	// Assert that string follows the regex pattern
+
+	/** Assert that string match the regex pattern */
 	regex(string: string, regex: RegExp, message?: string): void;
-	// Assert that expected matches a snapshot
+
+	/** Assert that expected matches a snapshot */
 	snapshot(expected: any, message?: string): void;
-	// Assert that expected matches a snapshot with option `id`
+
+	/** Assert that expected matches a snapshot with option `id` */
 	snapshot(expected: any, options: SnapshotOptions, message?: string): void;
-	// Assert that a function that returns an observable throws an error
+
+	/** Assert that a function that returns an observable throws an error */
 	throws(value: () => ObservableLike, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that a function that returns a promise throws an error
+
+	/** Assert that a function that returns a promise throws an error */
 	throws(value: () => PromiseLike<any>, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that a function that returns any value throws an error
+
+	/** Assert that a function throws an error */
 	throws(value: () => any, error?: ThrowsErrorValidator, message?: string): any;
-	// Assert that an observable throws an error
+
+	/** Assert that an observable throws an error */
 	throws(value: ObservableLike, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that a promise throws an error
+
+	/** Assert that a promise throws an error */
 	throws(value: PromiseLike<any>, error?: ThrowsErrorValidator, message?: string): Promise<any>;
-	// Assert that actual is equal to true
+
+	/** Assert that actual is equal to true */
 	true(actual: any, message?: string): void;
-	// Assert that actual is truthy ('0', 'false', [], {}, function() {}, etc.)
+
+	/** Assert that actual is truthy ('0', 'false', [], {}, function() {}, etc.) */
 	truthy(actual: any, message?: string): void;
 }