example formatting in docs

package.json

@@ -27,7 +27,7 @@
     "clean": "rm -rf dist lib lib-esm",
     "deploy": "npm run docs",
     "docs": "npm run docs:generate && npm run docs:deploy",
-    "docs:generate": "typedoc --out dist/docs --target es6 --theme minimal src",
+    "docs:generate": "typedoc --out dist/docs --exclude \"**/?(*.)+(test).ts\" --target es6 --theme minimal src",
     "docs:deploy": "touch dist/docs/.nojekyll && gh-pages --dotfiles -d dist/docs",
     "test": "jest --coverage --no-cache",
     "codecov": "npm run istanbul && codecov < coverage/lcov.info",

src/constants.ts

@@ -31,7 +31,9 @@ const constants = {
    * @memberof constants
    * @static
    * @example
+   * ```typescript
    * Interval(Interval.PI_LOW, Interval.PI_HIGH)
+   * ```
    * @name PI
    * @type {Interval}
    */

src/interval.ts

@@ -16,36 +16,29 @@ import round from './round'
  * @mixes utils
  * @mixes constants
  *
- * @see #bounded
- * @see #boundedSingleton
+ * @link #bounded
+ * @link #boundedSingleton
  *
  * @example
+ * ```typescript
  * new Interval(1, 2)  // {lo: 1, hi: 2}
- * @example
  * // function invocation without new is also supported
  * Interval(1, 2)   // {lo: 1, hi: 2}
- * @example
  * // with numbers
  * Interval(1, 2)   // {lo: 1, hi: 2}
  * Interval(1)      // {lo: 1, hi: 1}
- * @example
  * // with an array
  * Interval([1, 2]) // {lo: 1, hi: 2}
- * @example
  * // singleton intervals
  * var x = Interval(1)
  * var y = Interval(2)
  * Interval(x, y)   // {lo: 1, hi: 2}
- * @example
  * // when `lo > hi` it returns an empty interval
  * Interval(2, 1)   // {lo: Infinity, hi: -Infinity}
- * @example
  * // bounded interval
  * Interval().bounded(1, 2)  // { lo: 0.9999999999999999, hi: 2.0000000000000004 }
- * @example
  * // singleton bounded interval
  * Interval().boundedSingleton(2)  // {lo: 1.9999999999999998, hi: 2.0000000000000004}
- * @example
  * // half open and open intervals
  * // [2, 3]
  * Interval(2, 3)                     // {lo: 2, hi: 3}
@@ -55,6 +48,7 @@ import round from './round'
  * Interval().halfOpenRight(2, 3)     // {lo: 2, hi: 2.9999999999999996}
  * // (2, 3)
  * Interval().open(2, 3)              // {lo: 2.0000000000000004, hi: 2.9999999999999996}
+ * ```
  *
  * @param {number|array|Interval} lo The left endpoint of the interval if it's a
  * number or a singleton interval, if it's an array then an interval will be
@@ -131,11 +125,16 @@ export class Interval {
    * previous IEEE floating point value of `lo` and the right endpoint
    * is equal to the next IEEE floating point
    * value of `hi`, it's assumed that `lo <= hi`
+   *
    * @example
-   * var x = Interval().bounded(1, 2)
+   * ```typescript
+   * const x = Interval().bounded(1, 2)
    * x.lo < 1 // true, x.lo === 0.9999999999999999
    * x.hi > 2 // true, x.hi === 2.0000000000000004
+   * ```
+   *
    * @example
+   * ```typescript
    * // the correct representation of 1/3
    * var x = Interval().bounded(1/3, 1/3)
    * x.lo < 1/3 // true
@@ -145,6 +144,8 @@ export class Interval {
    * var next = Interval.round.safeNext
    * var x = Interval().set(1/3, next(1/3))
    * // x now represents 1/3 correctly
+   * ```
+   *
    * @param {number} lo
    * @param {number} hi
    * @return {Interval} The calling interval i.e. `this`
@@ -219,8 +220,11 @@ export class Interval {
    * NOTE: `Interval.round.disable` has no effect on this method
    *
    * @example
+   * ```typescript
    * // (2, 3)
    * Interval().open(2, 3)  // {lo: 2.0000000000000004, hi: 2.9999999999999996}
+   * ```
+   *
    * @param {number} lo
    * @param {number} hi
    * @return {Interval} The calling interval
@@ -235,8 +239,11 @@ export class Interval {
    * NOTE: `Interval.round.disable` has no effect on this method
    *
    * @example
+   * ```typescript
    * // (2, 3]
    * Interval().halfOpenLeft(2, 3)  // {lo: 2.0000000000000004, hi: 3}
+   * ```
+   *
    * @param {number} lo
    * @param {number} hi
    * @return {Interval} The calling interval
@@ -251,8 +258,11 @@ export class Interval {
    * NOTE: `Interval.round.disable` has no effect on this method
    *
    * @example
+   * ```typescript
    * // [2, 3)
    * Interval.halfOpenRight(2, 3)     // {lo: 2, hi: 2.9999999999999996}
+   * ```
+   *
    * @param {number} lo
    * @param {number} hi
    * @return {Interval} The calling interval
@@ -274,8 +284,10 @@ export class Interval {
    * @see Interval.clone
    * @name Interval.prototype
    * @example
+   * ```typescript
    * var x = Interval(2, 3)
    * x.clone()    // Interval(2, 3)
+   * ```
    * @return {Interval}
    */
   clone(): Interval {

src/operations/algebra.ts

@@ -12,19 +12,20 @@ import isSafeInteger from 'is-safe-integer'
  */
 
 /**
- * Computes x mod y (x - k * y)
+ * Computes `x mod y (x - k * y)`
+ *
  * @example
+ * ```typescript
  * Interval.fmod(
  *   Interval(5.3, 5.3),
  *   Interval(2, 2)
  * ) // Interval(1.3, 1.3)
- *
- * @example
  * Interval.fmod(
  *   Interval(5, 7),
  *   Interval(2, 3)
  * ) // Interval(2, 5)
  * // explanation: [5, 7] - [2, 3] * 1 = [2, 5]
+ * ```
  *
  * @param {Interval} x
  * @param {Interval} y
@@ -43,16 +44,18 @@ export function fmod(x: Interval, y: Interval): Interval {
 }
 
 /**
- * Computes 1 / x
+ * Computes `1 / x`
  *
  * @example
+ * ```typescript
  * Interval.multiplicativeInverse(
  *   Interval(2, 6)
  * )  // Interval(1/6, 1/2)
- * @example
  * Interval.multiplicativeInverse(
  *   Interval(-6, -2)
  * )  // Interval(-1/2, -1/6)
+ * ```
+ *
  * @param {Interval} x
  * @returns {Interval}
  */
@@ -85,37 +88,37 @@ export function multiplicativeInverse(x: Interval): Interval {
 }
 
 /**
- * Computes x^power given that `power` is an integer
+ * Computes `x^power` given that `power` is an integer
  *
- * If `power` is an Interval it must be a singletonInterval i.e. x^x is not
+ * If `power` is an Interval it must be a singletonInterval i.e. `x^x` is not
  * supported yet
  *
  * If `power` is a rational number use {@link nthRoot} instead
  *
  * @example
+ * ```typescript
  * // 2^{-2}
  * Interval.pow(
  *   Interval(2, 2),
  *   -2
  * )  // Interval(1/4, 1/4)
- * @example
  * // [2,3]^2
  * Interval.pow(
  *   Interval(2, 3),
  *   2
  * )  // Interval(4, 9)
- * @example
  * // [2,3]^0
  * Interval.pow(
  *   Interval(2, 3),
  *   0
  * )  // Interval(1, 1)
- * @example
  * // with a singleton interval
  * Interval.pow(
  *   Interval(2, 3),
  *   Interval(2)
  * )  // Interval(4, 9)
+ * ```
+ *
  * @param {Interval} x
  * @param {number|Interval} power A number of a singleton interval
  * @returns {Interval}
@@ -180,11 +183,15 @@ export function pow(x: Interval, power: Interval | number): Interval {
 }
 
 /**
- * Computes sqrt(x), alias for `nthRoot(x, 2)`
+ * Computes `sqrt(x)`, alias for `nthRoot(x, 2)`
+ *
  * @example
+ * ```typescript
  * Interval.sqrt(
  *   Interval(4, 9)
  * ) // Interval(prev(2), next(3))
+ * ```
+ *
  * @param {Interval} x
  * @returns {Interval}
  */
@@ -193,13 +200,16 @@ export function sqrt(x: Interval): Interval {
 }
 
 /**
- * Computes x^(1/n)
+ * Computes `x^(1/n)`
  *
  * @example
+ * ```typescript
  * Interval.nthRoot(
  *   Interval(-27, -8),
  *   3
  * ) // Interval(-3, -2)
+ * ```
+ *
  * @param {Interval} x
  * @param {number|Interval} n A number or a singleton interval
  * @return {Interval}