Updates typedoc syntax to address warnings (#733)

* Adds code fences (triple backticks) around example code in
  each doc comment.
* Replaces obsolete `[[Name]]` link usages with `{@link Name}`.

package.json

@@ -60,7 +60,7 @@
     "chai": "^4.3.6",
     "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.2.0",
-    "grunt": "^1.1.0",
+    "grunt": "^1.5.3",
     "grunt-babel": "^8.0.0",
     "grunt-browserify": "^5.3.0",
     "grunt-cli": "^1.3.2",

src/Ion.ts

@@ -53,7 +53,7 @@ export type ReaderOctetBuffer = ArrayBufferLike | ArrayLike<number>;
 export type ReaderBuffer = ReaderOctetBuffer | string;
 
 /**
- * Create an {Reader} over Ion data in a {ReaderBuffer}.
+ * Create an {@link Reader} over Ion data in a {@link ReaderBuffer}.
  *
  * @param buf       The Ion data to be used by the reader. Typically a string, UTF-8 encoded buffer (text), or raw
  *                  binary buffer.

src/IonDecimal.ts

@@ -61,8 +61,8 @@ export class Decimal {
   /**
    * Creates a new Decimal value using the provided coefficient and exponent values.
    *
-   * @param coefficient   See the class-level [[Decimal]] documentation for details.
-   * @param exponent      See the class-level [[Decimal]] documentation for details.
+   * @param coefficient   See the class-level {@link Decimal} documentation for details.
+   * @param exponent      See the class-level {@link Decimal} documentation for details.
    */
   constructor(coefficient: number, exponent: number);
 
@@ -73,8 +73,8 @@ export class Decimal {
    * the provided coefficient's sign will be used. If isNegative is specified but is not in agreement with
    * the coefficient's sign, the value of isNegative takes precedence.
    *
-   * @param coefficient   See the class-level [[Decimal]] documentation for details.
-   * @param exponent      See the class-level [[Decimal]] documentation for details.
+   * @param coefficient   See the class-level {@link Decimal} documentation for details.
+   * @param exponent      See the class-level {@link Decimal} documentation for details.
    * @param isNegative    Must be set to 'true' when constructing -0. May be omitted otherwise.
    */
   constructor(coefficient: bigint, exponent: number, isNegative?: boolean);
@@ -269,7 +269,7 @@ export class Decimal {
    * Returns a BigInt representing the coefficient of this Decimal value.
    *
    * Note that the BigInt data type is unable to represent -0 natively. If you wish to check for a -0 coefficient,
-   * test whether the coefficient is zero and then call [[isNegative]].
+   * test whether the coefficient is zero and then call {@link isNegative}.
    */
   getCoefficient(): bigint {
     return this._coefficient;

src/IonReader.ts

@@ -18,7 +18,7 @@ import { Decimal } from "./IonDecimal";
 import { Timestamp } from "./IonTimestamp";
 import { IonType } from "./IonType";
 
-/** Represents the possible return values of [[Reader.value]]. */
+/** Represents the possible return values of {@link Reader.value}. */
 export type ReaderScalarValue =
   | null
   | boolean
@@ -32,12 +32,12 @@ export type ReaderScalarValue =
 /**
  * A pull parser interface over Ion data.
  *
- * Generally, users will use [[next]] and [[stepIn]] and [[stepOut]]
+ * Generally, users will use {@link next} and {@link stepIn} and {@link stepOut}
  * to traverse the structure of the data. The **Value** suffixed methods are
- * used to extract the scalar data out of the current position of the [[Reader]].
+ * used to extract the scalar data out of the current position of the {@link Reader}.
  *
- * [[Reader]] instances start *before* a value, thus you have to
- * invoke [[next]] to position a newly created reader on the first value.
+ * {@link Reader} instances start *before* a value, thus you have to
+ * invoke {@link next} to position a newly created reader on the first value.
  */
 export interface Reader {
   /**
@@ -56,16 +56,16 @@ export interface Reader {
    * mid-stream system level values that must be processed to guarantee that the
    * Reader is in a valid state. It is safe, however, to start at the beginning of a data
    * source and call next() until you reach the desired position, as the reader
-   * will still have the opportunity to process system-level values along the way.)
+   * will still have the opportunity to process system-level values along the way.
    *
-   * @returns the [[number]] of bytes or UTF-16 code units that the reader has processed.
+   * @returns the number of bytes or UTF-16 code units that the reader has processed.
    */
   position(): number;
 
   /**
    * Advances the reader to the next value in the stream at the current depth.
    *
-   * @return The corresponding [[IonType]] of the value the reader moves to, or `null`
+   * @return The corresponding {@link IonType} of the value the reader moves to, or `null`
    *  if the reader is at the end of the stream or container.
    */
   next(): IonType | null;
@@ -74,15 +74,15 @@ export interface Reader {
    * Steps into the container the reader is currently positioned on.  Note that this
    * positions the reader *before* the first value within the container.
    *
-   * @throw Error if the reader is not positioned on a container or the container [[isNull]].
+   * @throw Error if the reader is not positioned on a container or the container {@link isNull}.
    */
   stepIn(): void;
 
   /**
    * Steps out of the current container.  This is only valid when the reader is inside of a container
    * (i.e. `depth() > 0`).  Note that the positions the reader *after* the container that was
    * stepped out of, but *before* the next value after the container.  One should generally
-   * call [[next]] after invoking this method.
+   * call {@link next} after invoking this method.
    *
    * @throw Error if the reader is not positioned within a container.
    */
@@ -110,7 +110,7 @@ export interface Reader {
   isNull(): boolean;
 
   /**
-   * Returns the [[IonType]] associated with the current value.
+   * Returns the {@link IonType} associated with the current value.
    *
    * @return `null` if the reader is not positioned on a value.
    */
@@ -119,7 +119,7 @@ export interface Reader {
   /**
    * Returns the current value as a `boolean`.  This is only valid if `type() == IonTypes.BOOL`.
    *
-   * @return `null` if the current Ion value [[isNull]].
+   * @return `null` if the current Ion value {@link isNull}.
    *
    * @throw Error when the reader is not positioned on a `bool` typed value.
    */
@@ -129,7 +129,7 @@ export interface Reader {
    * Returns the current value as a `Uint8Array`.  This is only valid if `type() == IonTypes.CLOB`
    * or `type() == IonTypes.BLOB`.
    *
-   * @return `null` if the current Ion value [[isNull]].
+   * @return `null` if the current Ion value {@link isNull}.
    *
    * @throw Error when the reader is not positioned on a `clob` or `blob` typed value.
    * @deprecated since version 4.2. Use the `uInt8ArrayValue` method instead.
@@ -140,16 +140,16 @@ export interface Reader {
    * Returns the current value as a `Uint8Array`.  This is only valid if `type() == IonTypes.CLOB`
    * or `type() == IonTypes.BLOB`.
    *
-   * @return `null` if the current Ion value [[isNull]].
+   * @return `null` if the current Ion value {@link isNull}.
    *
    * @throw Error when the reader is not positioned on a `clob` or `blob` typed value.
    */
   uInt8ArrayValue(): Uint8Array | null;
 
   /**
-   * Returns the current value as a [[Decimal]].  This is only valid if `type() == IonTypes.DECIMAL`.
+   * Returns the current value as a {@link Decimal}.  This is only valid if `type() == IonTypes.DECIMAL`.
    *
-   * @return `null` if the current Ion value [[isNull]].
+   * @return `null` if the current Ion value {@link isNull}.
    *
    * @throw Error when the reader is not positioned on a `decimal` typed value.
    */
@@ -159,7 +159,7 @@ export interface Reader {
    * Returns the current value as a `number`.  This is only valid if `type() == IonTypes.INT`
    * or `type() == IonTypes.FLOAT`.
    *
-   * @return `null` if the current Ion value [[isNull]]. For `int` values that are outside of
+   * @return `null` if the current Ion value {@link isNull}. For `int` values that are outside of
    *  the range specified by `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER`, this method
    *  will truncate the result.
    *
@@ -170,7 +170,7 @@ export interface Reader {
   /**
    * Returns the current value as a `BigInt`.  This is only valid if `type() == IonTypes.INT`.
    *
-   * @return `null` if the current Ion value [[isNull]] or a BigInt containing the deserialized integer.
+   * @return `null` if the current Ion value {@link isNull} or a BigInt containing the deserialized integer.
    *
    * @throw Error when the reader is not positioned on an `int` typed value.
    */
@@ -180,24 +180,24 @@ export interface Reader {
    * Indicates whether the current int value is small enough to be stored in a number without loss of precision
    * or if a BigInt is required.
    *
-   * @return [[IntSize.Number]] if the value will fit in a number, [[IntSize.BigInt]] otherwise.
+   * @return {@link IntSize.Number} if the value will fit in a number, {@link IntSize.BigInt} otherwise.
    */
   intSize(): IntSize;
 
   /**
    * Returns the current value as a `string`.  This is only valid if `type() == IonTypes.STRING`
    * or `type() == IonTypes.SYMBOL`.
    *
-   * @return `null` if the current Ion value [[isNull]].
+   * @return `null` if the current Ion value {@link isNull}.
    *
    * @throw Error when the reader is not positioned on a `string` or `symbol` typed value.
    */
   stringValue(): string | null;
 
   /**
-   * Returns the current value as a [[Timestamp]].  This is only valid if `type() == IonTypes.TIMESTAMP`.
+   * Returns the current value as a {@link Timestamp}.  This is only valid if `type() == IonTypes.TIMESTAMP`.
    *
-   * @return `null` if the current Ion value [[isNull]].
+   * @return `null` if the current Ion value {@link isNull}.
    *
    * @throw Error when the reader is not positioned on a `timestamp` typed value.
    */
@@ -206,7 +206,7 @@ export interface Reader {
   /**
    * Returns the current scalar value.  This is only valid when `type().scalar == true`.
    *
-   * @return `null` if the current value is [[isNull]], equivalent to the corresponding `xxxValue` methods
+   * @return `null` if the current value is {@link isNull}, equivalent to the corresponding `xxxValue` methods
    *  for all scalar types.
    *
    * @throw Error when the reader is not positioned on a scalar value.

src/IonTextWriter.ts

@@ -452,8 +452,8 @@ export class TextWriter extends AbstractWriter {
 
   /**
    * Ion's textual representation doesn't distinguish between 32- and 64-bit floats.
-   * This method provides a common implementation of [[writeFloat32]] and [[writeFloat64]], which
-   * are distinct functions to satisfy the [[Writer]] interface.
+   * This method provides a common implementation of {@link writeFloat32} and {@link writeFloat64}, which
+   * are distinct functions to satisfy the {@link Writer} interface.
    *
    * @param value - A numeric value to write as an Ion float.
    */
@@ -463,7 +463,7 @@ export class TextWriter extends AbstractWriter {
 
   /**
    * This method provides an implementation of Serializer<number> that can be used in calls to
-   * [[_writeValue]]. It maintains the expected binding to `this` even when used as a callback.
+   * {@link _writeValue}. It maintains the expected binding to `this` even when used as a callback.
    *
    * @param value
    */

src/IonWriter.ts

@@ -22,7 +22,7 @@ import { IonType } from "./IonType";
  * Serializes data in Ion text or binary format to an implementation defined buffer.
  */
 export interface Writer {
-  /** Writes a null value of the given [[IonType]]. */
+  /** Writes a null value of the given {@link IonType}. */
   writeNull(type: IonType): void;
 
   /**
@@ -58,16 +58,16 @@ export interface Writer {
   writeFloat64(value: number | null): void;
 
   /**
-   * Writes a [[Decimal]] value as an Ion `decimal` value.
+   * Writes a {@link Decimal} value as an Ion `decimal` value.
    *
-   * @param value The [[Decimal]] to write, which may be `null` to write a `null.decimal`.
+   * @param value The {@link Decimal} to write, which may be `null` to write a `null.decimal`.
    */
   writeDecimal(value: Decimal | null): void;
 
   /**
-   * Writes a [[Timestamp]] value as an Ion `timestamp` value.
+   * Writes a {@link Timestamp} value as an Ion `timestamp` value.
    *
-   * @param value The [[Timestamp]] to write, which may be `null` to write a `null.timestamp`.
+   * @param value The {@link Timestamp} to write, which may be `null` to write a `null.timestamp`.
    */
   writeTimestamp(value: Timestamp | null): void;
 
@@ -127,7 +127,7 @@ export interface Writer {
   /**
    * Writes the field name for a member of a `struct`.
    *
-   * @throws Error if the [[Writer]] is not within a `struct` or this method was already
+   * @throws Error if the {@link Writer} is not within a `struct` or this method was already
    *  called before a value was written.
    */
   writeFieldName(fieldName: string): void;
@@ -163,17 +163,17 @@ export interface Writer {
   /**
    * Flushes data to the internal buffer and finalizes the Ion stream.
    *
-   * @throws Error if the [[Writer]] is already closed or the writer is not
+   * @throws Error if the {@link Writer} is already closed or the writer is not
    *  at the top-level (i.e. inside of a container).
    */
   close(): void;
 
   /**
    * Retrieves the serialized buffer as an array of octets.  The buffer will
    * be either a UTF-8 encoded buffer for Ion text or Ion binary.  The buffer is
-   * not well-defined until [[close]] is invoked.
+   * not well-defined until {@link close} is invoked.
    *
-   * @throws Error if [[close]] has not been invoked.
+   * @throws Error if {@link close} has not been invoked.
    */
   getBytes(): Uint8Array;
 

src/dom/Boolean.ts

@@ -23,6 +23,7 @@ const _fromJsConstructor: FromJsConstructor = new FromJsConstructorBuilder()
  * > Any object of which the value is not undefined or null, including a Boolean object
  *   whose value is false, evaluates to true when passed to a conditional statement.
  *
+ * ```javascript
  *      var b = false;
  *      if (b) {
  *          // this code will NOT be executed
@@ -32,7 +33,7 @@ const _fromJsConstructor: FromJsConstructor = new FromJsConstructorBuilder()
  *      if (b) {
  *          // this code WILL be executed
  *      }
- *
+ * ```
  * [1] http://amzn.github.io/ion-docs/docs/spec.html#bool
  * [2] https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean#Description
  */

src/dom/Struct.ts

@@ -7,20 +7,26 @@ import { PathElement, Value } from "./Value";
  *
  * Struct fields can be accessed as properties on this object. For example:
  *
+ * ```typescript
  *    let s: any = ion.load('{foo: 1, bar: 2, baz: qux::3}');
  *    assert.equal(6, s.foo + s['bar'] + s.baz);
+ * ```
  *
  * If a field in the struct has the same name as a method on the Struct class, attempting to access that property
  * will always resolve to the method.
  *
+ * ```typescript
  *     let s: any = ion.load('{fieldNames: ["foo", "bar", "baz"]}'); // Conflicts with Struct#fieldNames()
  *     assert.deepEqual(s.fieldNames, ["foo", "bar", "baz"]); // Fails; `s.fieldNames` is a method
  *     assert.deepEqual(s.fieldNames(), ["fieldNames"]); // Passes
+ * ```
  *
  * Unlike direct property accesses, Struct's get() method will only resolve to fields.
  *
+ * ```typescript
  *     let s: any = ion.load('{fieldNames: ["foo", "bar", "baz"]}'); // Conflicts with Struct#fieldNames()
  *     assert.equal(s.get('fieldNames', 0).stringValue(), "foo"); // Passes
+ * ```
  *
  * [1] http://amzn.github.io/ion-docs/docs/spec.html#struct
  */

src/dom/Value.ts

@@ -110,17 +110,19 @@ export interface Value {
    * with a given field name instead of just the last one. For example, for the
    * following struct:
    *
+   * ```javascript
    *     {
    *         foo: 1,
    *         foo: null,
    *         foo: true,
    *     }
+   * ```
    *
    * a call to `get("foo")` would return a `dom.Boolean` representing `true`
    * while a call to `getAll("foo")` would return an `Array` of
    * `dom.Value`s: `[1, null, true]`.
    *
-   * @param One or more values to be used to index into the Value.
+   * @param pathElements One or more values to be used to index into the Value.
    * @returns null if no value is found at the specified path. Otherwise, returns the discovered Value.
    */
   getAll(...pathElements: PathElement[]): Value[] | null;
@@ -143,11 +145,13 @@ export interface Value {
    * to a field name. For example, for the
    * following struct:
    *
+   * ```javascript
    *     {
    *         foo: 1,
    *         foo: null,
    *         foo: true,
    *     }
+   * ```
    *
    * a call to `fields()` would return a field name "foo" with a `dom.Boolean` representing `true`
    * while a call to `allFields()` would return  a field name "foo" with an `Array` of

src/events/IonEventStream.ts

@@ -606,7 +606,10 @@ export class IonEventStream {
   }
 
   /** Parse the field name (Symbol Token) into text/symbol
-   *  example: {event_type: SCALAR, ion_type: INT, field_name: {text:"foo"}, value_text: "1", value_binary: [0x21, 0x01], depth:1}
+   *  example:
+   *  ```javascript
+   *  {event_type: SCALAR, ion_type: INT, field_name: {text:"foo"}, value_text: "1", value_binary: [0x21, 0x01], depth:1}
+   *  ```
    *  for more information: https://github.com/amzn/ion-test-driver#symboltoken-1
    */
   private resolveFieldNameFromSerializedSymbolToken(): string | null {