Unify documentation (#157)

readme.md

@@ -159,41 +159,37 @@ These options will be overridden if a `tsconfig.json` file is found in your proj
 
 ## Assertions
 
-### expectType<T>(value)
+### expectType<T>(expression: T)
 
-Check that the type of `value` is identical to type `T`.
+Asserts that the type of `expression` is identical to type `T`.
 
-### expectNotType<T>(value)
+### expectNotType<T>(expression: any)
 
-Check that the type of `value` is not identical to type `T`.
+Asserts that the type of `expression` is not identical to type `T`.
 
-### expectAssignable<T>(value)
+### expectAssignable<T>(expression: T)
 
-Check that the type of `value` is assignable to type `T`.
+Asserts that the type of `expression` is assignable to type `T`.
 
-### expectNotAssignable<T>(value)
+### expectNotAssignable<T>(expression: any)
 
-Check that the type of `value` is not assignable to type `T`.
+Asserts that the type of `expression` is not assignable to type `T`.
 
-### expectError(function)
+### expectError<T = any>(expression: T)
 
-Check if the function call has argument type errors.
+Asserts that `expression` throws an error.
 
-### expectError<T>(value)
+### expectDeprecated(expression: any)
 
-Check if a value is of the provided type `T`.
+Asserts that `expression` is marked as [`@deprecated`](https://jsdoc.app/tags-deprecated.html).
 
-### expectDeprecated(value)
+### expectNotDeprecated(expression: any)
 
-Check that `value` is marked a [`@deprecated`](https://jsdoc.app/tags-deprecated.html).
+Asserts that `expression` is not marked as [`@deprecated`](https://jsdoc.app/tags-deprecated.html).
 
-### expectNotDeprecated(value)
+### printType(expression: any)
 
-Check that `value` is not marked a [`@deprecated`](https://jsdoc.app/tags-deprecated.html).
-
-### printType(value)
-
-Print the type of `value` as a warning.
+Prints the type of `expression` as a warning.
 
 Useful if you don't know the exact type of the expression passed to `printType()` or the type is too complex to write out by hand.
 

source/lib/assertions/assert.ts

@@ -1,59 +1,59 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 
 /**
- * Check that the type of `value` is identical to type `T`.
+ * Asserts that the type of `expression` is identical to type `T`.
  *
- * @param value - Value that should be identical to type `T`.
+ * @param expression - Expression that should be identical to type `T`.
  */
 // @ts-expect-error
-export const expectType = <T>(value: T) => {
+export const expectType = <T>(expression: T) => {
 	// Do nothing, the TypeScript compiler handles this for us
 };
 
 /**
- * Check that the type of `value` is not identical to type `T`.
+ * Asserts that the type of `expression` is not identical to type `T`.
  *
- * @param value - Value that should be identical to type `T`.
+ * @param expression - Expression that should not be identical to type `T`.
  */
 // @ts-expect-error
-export const expectNotType = <T>(value: any) => {
+export const expectNotType = <T>(expression: any) => {
 	// eslint-disable-next-line no-warning-comments
 	// TODO Use a `not T` type when possible https://github.com/microsoft/TypeScript/pull/29317
 	// Do nothing, the TypeScript compiler handles this for us
 };
 
 /**
- * Check that the type of `value` is assignable to type `T`.
+ * Asserts that the type of `expression` is assignable to type `T`.
  *
- * @param value - Value that should be assignable to type `T`.
+ * @param expression - Expression that should be assignable to type `T`.
  */
 // @ts-expect-error
-export const expectAssignable = <T>(value: T) => {
+export const expectAssignable = <T>(expression: T) => {
 	// Do nothing, the TypeScript compiler handles this for us
 };
 
 /**
- * Check that the type of `value` is not assignable to type `T`.
+ * Asserts that the type of `expression` is not assignable to type `T`.
  *
- * @param value - Value that should not be assignable to type `T`.
+ * @param expression - Expression that should not be assignable to type `T`.
  */
 // @ts-expect-error
-export const expectNotAssignable = <T>(value: any) => {
+export const expectNotAssignable = <T>(expression: any) => {
 	// Do nothing, the TypeScript compiler handles this for us
 };
 
 /**
- * Assert the value to throw an argument error.
+ * Asserts that `expression` throws an error.
  *
- * @param value - Value that should be checked.
+ * @param expression - Expression that should throw an error.
  */
 // @ts-expect-error
-export const expectError = <T = any>(value: T) => {
+export const expectError = <T = any>(expression: T) => {
 	// Do nothing, the TypeScript compiler handles this for us
 };
 
 /**
- * Assert that the `expression` provided is marked as `@deprecated`.
+ * Asserts that `expression` is marked as `@deprecated`.
  *
  * @param expression - Expression that should be marked as `@deprecated`.
  */
@@ -63,7 +63,7 @@ export const expectDeprecated = (expression: any) => {
 };
 
 /**
- * Assert that the `expression` provided is not marked as `@deprecated`.
+ * Asserts that `expression` is not marked as `@deprecated`.
  *
  * @param expression - Expression that should not be marked as `@deprecated`.
  */
@@ -73,7 +73,7 @@ export const expectNotDeprecated = (expression: any) => {
 };
 
 /**
- * Will print a warning with the type of the expression passed as argument.
+ * Prints the type of `expression` as a warning.
  *
  * @param expression - Expression whose type should be printed as a warning.
  */

source/lib/assertions/handlers/assignability.ts

@@ -3,10 +3,10 @@ import {Diagnostic} from '../../interfaces';
 import {makeDiagnostic} from '../../utils';
 
 /**
- * Verifies that the argument of the assertion is not assignable to the generic type of the assertion.
+ * Asserts that the argument of the assertion is not assignable to the generic type of the assertion.
  *
  * @param checker - The TypeScript type checker.
- * @param nodes - The `expectType` AST nodes.
+ * @param nodes - The `expectNotAssignable` AST nodes.
  * @return List of custom diagnostics.
  */
 export const isNotAssignable = (checker: TypeChecker, nodes: Set<CallExpression>): Diagnostic[] => {

source/lib/assertions/handlers/expect-deprecated.ts

@@ -37,7 +37,7 @@ const expectDeprecatedHelper = (options: Options): Handler => {
 };
 
 /**
- * Assert that the argument from the `expectDeprecated` statement is marked as `@deprecated`.
+ * Asserts that the argument of the assertion is marked as `@deprecated`.
  * If it's not marked as `@deprecated`, an error diagnostic is returned.
  *
  * @param checker - The TypeScript type checker.
@@ -50,7 +50,7 @@ export const expectDeprecated = expectDeprecatedHelper({
 });
 
 /**
- * Assert that the argument from the `expectNotDeprecated` statement is not marked as `@deprecated`.
+ * Asserts that the argument of the assertion is not marked as `@deprecated`.
  * If it's marked as `@deprecated`, an error diagnostic is returned.
  *
  * @param checker - The TypeScript type checker.

source/lib/assertions/handlers/identicality.ts

@@ -3,7 +3,7 @@ import {Diagnostic} from '../../interfaces';
 import {makeDiagnostic} from '../../utils';
 
 /**
- * Verifies that the argument of the assertion is identical to the generic type of the assertion.
+ * Asserts that the argument of the assertion is identical to the generic type of the assertion.
  *
  * @param checker - The TypeScript type checker.
  * @param nodes - The `expectType` AST nodes.
@@ -52,7 +52,7 @@ export const isIdentical = (checker: TypeChecker, nodes: Set<CallExpression>): D
 };
 
 /**
- * Verifies that the argument of the assertion is not identical to the generic type of the assertion.
+ * Asserts that the argument of the assertion is not identical to the generic type of the assertion.
  *
  * @param checker - The TypeScript type checker.
  * @param nodes - The `expectNotType` AST nodes.

source/lib/assertions/handlers/informational.ts

@@ -3,7 +3,7 @@ import {Diagnostic} from '../../interfaces';
 import {makeDiagnostic} from '../../utils';
 
 /**
- * Emits a warning diagnostic for every call experession encountered containing the type of the first argument.
+ * Prints the type of the argument of the assertion as a warning.
  *
  * @param checker - The TypeScript type checker.
  * @param nodes - The `printType` AST nodes.