add js docs for node spec definitions

packages/core/src/Node.ts

@@ -423,12 +423,22 @@ declare module '@tiptap/core' {
       | null
 
     /**
-     * TopNode
+     * Defines if this node should be a top level node (doc)
+     * @default false
+     * @example true
      */
     topNode?: boolean
 
     /**
-     * Content
+     * The content expression for this node, as described in the [schema
+     * guide](/docs/guide/#schema.content_expressions). When not given,
+     * the node does not allow any content.
+     *
+     * You can read more about it on the Prosemirror documentation here
+     * @see https://prosemirror.net/docs/guide/#schema.content_expressions
+     * @default undefined
+     * @example content: 'block+'
+     * @example content: 'headline paragraph block*'
      */
     content?:
       | NodeSpec['content']
@@ -441,7 +451,13 @@ declare module '@tiptap/core' {
         }) => NodeSpec['content'])
 
     /**
-     * Marks
+     * The marks that are allowed inside of this node. May be a
+     * space-separated string referring to mark names or groups, `"_"`
+     * to explicitly allow all marks, or `""` to disallow marks. When
+     * not given, nodes with inline content default to allowing all
+     * marks, other nodes default to not allowing marks.
+     *
+     * @example marks: 'strong em'
      */
     marks?:
       | NodeSpec['marks']
@@ -454,7 +470,16 @@ declare module '@tiptap/core' {
         }) => NodeSpec['marks'])
 
     /**
-     * Group
+     * The group or space-separated groups to which this node belongs,
+     * which can be referred to in the content expressions for the
+     * schema.
+     *
+     * By default Tiptap uses the groups 'block' and 'inline' for nodes. You
+     * can also use custom groups if you want to group specific nodes together
+     * and handle them in your schema.
+     * @example group: 'block'
+     * @example group: 'inline'
+     * @example group: 'customBlock' // this uses a custom group
      */
     group?:
       | NodeSpec['group']
@@ -467,7 +492,7 @@ declare module '@tiptap/core' {
         }) => NodeSpec['group'])
 
     /**
-     * Inline
+     * Should be set to true for inline nodes. (Implied for text nodes.)
      */
     inline?:
       | NodeSpec['inline']
@@ -480,7 +505,11 @@ declare module '@tiptap/core' {
         }) => NodeSpec['inline'])
 
     /**
-     * Atom
+     * Can be set to true to indicate that, though this isn't a [leaf
+     * node](https://prosemirror.net/docs/ref/#model.NodeType.isLeaf), it doesn't have directly editable
+     * content and should be treated as a single unit in the view.
+     *
+     * @example atom: true
      */
     atom?:
       | NodeSpec['atom']
@@ -493,7 +522,12 @@ declare module '@tiptap/core' {
         }) => NodeSpec['atom'])
 
     /**
-     * Selectable
+     * Controls whether nodes of this type can be selected as a [node
+     * selection](https://prosemirror.net/docs/ref/#state.NodeSelection). Defaults to true for non-text
+     * nodes.
+     *
+     * @default true
+     * @example selectable: false
      */
     selectable?:
       | NodeSpec['selectable']
@@ -506,7 +540,11 @@ declare module '@tiptap/core' {
         }) => NodeSpec['selectable'])
 
     /**
-     * Draggable
+     * Determines whether nodes of this type can be dragged without
+     * being selected. Defaults to false.
+     *
+     * @default: false
+     * @example: draggable: true
      */
     draggable?:
       | NodeSpec['draggable']
@@ -519,7 +557,8 @@ declare module '@tiptap/core' {
         }) => NodeSpec['draggable'])
 
     /**
-     * Code
+     * Can be used to indicate that this node contains code, which
+     * causes some commands to behave differently.
      */
     code?:
       | NodeSpec['code']
@@ -532,7 +571,15 @@ declare module '@tiptap/core' {
         }) => NodeSpec['code'])
 
     /**
-     * Whitespace
+     * Controls way whitespace in this a node is parsed. The default is
+     * `"normal"`, which causes the [DOM parser](https://prosemirror.net/docs/ref/#model.DOMParser) to
+     * collapse whitespace in normal mode, and normalize it (replacing
+     * newlines and such with spaces) otherwise. `"pre"` causes the
+     * parser to preserve spaces inside the node. When this option isn't
+     * given, but [`code`](https://prosemirror.net/docs/ref/#model.NodeSpec.code) is true, `whitespace`
+     * will default to `"pre"`. Note that this option doesn't influence
+     * the way the node is rendered—that should be handled by `toDOM`
+     * and/or styling.
      */
     whitespace?:
       | NodeSpec['whitespace']
@@ -545,7 +592,12 @@ declare module '@tiptap/core' {
         }) => NodeSpec['whitespace'])
 
     /**
-     * Defining
+     * When enabled, enables both
+     * [`definingAsContext`](https://prosemirror.net/docs/ref/#model.NodeSpec.definingAsContext) and
+     * [`definingForContent`](https://prosemirror.net/docs/ref/#model.NodeSpec.definingForContent).
+     *
+     * @default false
+     * @example isolating: true
      */
     defining?:
       | NodeSpec['defining']
@@ -558,7 +610,10 @@ declare module '@tiptap/core' {
         }) => NodeSpec['defining'])
 
     /**
-     * Isolating
+     * When enabled (default is false), the sides of nodes of this type
+     * count as boundaries that regular editing operations, like
+     * backspacing or lifting, won't cross. An example of a node that
+     * should probably have this enabled is a table cell.
      */
     isolating?:
       | NodeSpec['isolating']
@@ -571,7 +626,14 @@ declare module '@tiptap/core' {
         }) => NodeSpec['isolating'])
 
     /**
-     * Parse HTML
+     * Associates DOM parser information with this node, which can be
+     * used by [`DOMParser.fromSchema`](https://prosemirror.net/docs/ref/#model.DOMParser^fromSchema) to
+     * automatically derive a parser. The `node` field in the rules is
+     * implied (the name of this node will be filled in automatically).
+     * If you supply your own parser, you do not need to also specify
+     * parsing rules in your schema.
+     *
+     * @example parseHTML: [{ tag: 'div', attrs: { 'data-id': 'my-block' } }]
      */
     parseHTML?: (this: {
       name: string
@@ -582,7 +644,24 @@ declare module '@tiptap/core' {
     }) => NodeSpec['parseDOM']
 
     /**
-     * Render HTML
+     * A description of a DOM structure. Can be either a string, which is
+     * interpreted as a text node, a DOM node, which is interpreted as
+     * itself, a `{dom, contentDOM}` object, or an array.
+     *
+     * An array describes a DOM element. The first value in the array
+     * should be a string—the name of the DOM element, optionally prefixed
+     * by a namespace URL and a space. If the second element is plain
+     * object, it is interpreted as a set of attributes for the element.
+     * Any elements after that (including the 2nd if it's not an attribute
+     * object) are interpreted as children of the DOM elements, and must
+     * either be valid `DOMOutputSpec` values, or the number zero.
+     *
+     * The number zero (pronounced “hole”) is used to indicate the place
+     * where a node's child nodes should be inserted. If it occurs in an
+     * output spec, it should be the only child element in its parent
+     * node.
+     *
+     * @example toDOM: ['div[data-id="my-block"]', { class: 'my-block' }, 0]
      */
     renderHTML?:
       | ((
@@ -601,7 +680,8 @@ declare module '@tiptap/core' {
       | null
 
     /**
-     * Render Text
+     * renders the node as text
+     * @example renderText: () => 'foo
      */
     renderText?:
       | ((
@@ -622,7 +702,8 @@ declare module '@tiptap/core' {
       | null
 
     /**
-     * Add Attributes
+     * Add attributes to the node
+     * @example addAttributes: () => ({ class: 'foo' })
      */
     addAttributes?: (this: {
       name: string