Lint Typed Lists

[avivkeller]

The web generator currently identifies a Typed list as a list item that contains a property name, type, and optionally a description. These lists are frequently used in our documentation to describe properties, type parameters, return values, and similar constructs.

However, during parser development, I noticed inconsistent formatting across various API documents. This inconsistency complicates parsing logic. To address this, we should define consistent format for Typed lists and implement a linter to enforce this format across all documentation.

---

My proposed definition is as follows:

A Typed list is a special form of an unordered list composed of Typed List Entries that describe a optional property, type, and optional description.

• A Typed list must be an unordered list using the * bullet format.

• Each entry must begin with a * to denote a list item.

• Each entry may begin with a property name, wrapped in backticks: `propertyName`

  • Alternatively, the entry may begin with Returns: to indicate a return type.
  • Type: to indicate a lack of property name.
  • Extends: to indicate inheritance or extension

• Each entry must include one or more types, wrapped in curly braces: {Type}, separated by | if multiple types exist.

  • This is optional for Returns: entries.

• Each entry may include a description following the type(s), written as plain text.

* `id` {string} The unique identifier.
* `isActive` {boolean} Indicates whether the item is active.
* Returns: {object|Error} The result.

[avivkeller]

CC @nodejs/documentation

FWIW I plan to open a PR to nodejs/node with improvements to the documentation format.