add comments to all commands

docs/src/docPages/api/commands.md

@@ -95,18 +95,18 @@ Have a look at all of the core commands listed below. They should give you a goo
 | .updateNodeAttributes() | Update attributes of a node.                              |
 
 ### Lists
-| Command          | Description                                            |
+| Command          | Description                                 |
-| ---------------- | ------------------------------------------------------ |
+| ---------------- | ------------------------------------------- |
-| .liftListItem()  | Lift the list item into a wrapping list.               |
+| .liftListItem()  | Lift the list item into a wrapping list.    |
-| .sinkListItem()  | Sink the list item down into an inner list.            |
+| .sinkListItem()  | Sink the list item down into an inner list. |
-| .splitListItem() | Splits a textblock of a list item into two list items. |
+| .splitListItem() | Splits one list item into two list items.   |
-| .toggleList()    | Toggle between different list types.                   |
+| .toggleList()    | Toggle between different list types.        |
-| .wrapInList()    | Wrap a node in a list.                                 |
+| .wrapInList()    | Wrap a node in a list.                      |
 
 ### Selection
 | Command            | Description                             |
 | ------------------ | --------------------------------------- |
-| .blur()            | Blurs the editor.                       |
+| .blur()            | Removes focus from the editor.          |
 | .deleteSelection() | Delete the selection, if there is one.  |
 | .focus()           | Focus the editor at the given position. |
 | .scrollIntoView()  | Scroll the selection into view.         |

docs/src/docPages/guide/build-custom-extensions.md

@@ -282,6 +282,10 @@ const CustomParagraph = Paragraph.extend({
 })
 ```
 
+:::warning Use the commands parameter inside of addCommands
+All commands are also available through ~~this.editor.commands~~, but inside of `addCommands` you must use the `commands` parameter that’s passed to it.
+:::
+
 ### Keyboard shortcuts
 Most core extensions come with sensible keyboard shortcut defaults. Depending on what you want to build, you’ll likely want to change them though. With the `addKeyboardShortcuts()` method you can overwrite the predefined shortcut map:
 

packages/core/src/extensions/commands.ts

@@ -31,33 +31,117 @@ import wrapInList from '../commands/wrapInList'
 export const Commands = createExtension({
   addCommands() {
     return {
+      /**
+       * Removes focus from the editor.
+       */
       blur,
+      /**
+       * Clear the whole document.
+       */
       clearContent,
+      /**
+       * Normalize nodes to a simple paragraph.
+       */
       clearNodes,
+      /**
+       * Delete the selection, if there is one.
+       */
       deleteSelection,
+      /**
+       * Extends the text selection to the current mark.
+       */
       extendMarkRange,
+      /**
+       * Focus the editor at the given position.
+       */
       focus,
+      /**
+       * Insert a string of HTML at the current position.
+       */
       insertHTML,
+      /**
+       * Insert a string of text at the current position.
+       */
       insertText,
+      /**
+       * Lift the list item into a wrapping list.
+       */
       liftListItem,
+      /**
+       * Remove all marks in the current selection.
+       */
       removeMark,
+      /**
+       * Remove all marks in the current selection.
+       */
       removeMarks,
+      /**
+       * Resets all node attributes to the default value.
+       */
       resetNodeAttributes,
+      /**
+       * Scroll the selection into view.
+       */
       scrollIntoView,
+      /**
+       * Select the whole document.
+       */
       selectAll,
+      /**
+       * Select the parent node.
+       */
       selectParentNode,
+      /**
+       * Replace a given range with a node.
+       */
       setBlockType,
+      /**
+       * Replace the whole document with new content.
+       */
       setContent,
+      /**
+       * Sink the list item down into an inner list.
+       */
       sinkListItem,
+      /**
+       * Forks a new node from an existing node.
+       */
       splitBlock,
+      /**
+       * Splits one list item into two list items.
+       */
       splitListItem,
+      /**
+       * Toggle a node with another node.
+       */
       toggleBlockType,
+      /**
+       * Toggle between different list types.
+       */
       toggleList,
+      /**
+       * Toggle a mark on and off.
+       */
       toggleMark,
+      /**
+       * Wraps nodes in another node, or removes an existing wrap.
+       */
       toggleWrap,
+      /**
+       * Runs one command after the other and stops at the first which returns true.
+       */
       try: tryCommand,
+      /**
+       * Update a mark with new attributes.
+       */
       updateMarkAttributes,
+      /**
+       * Update attributes of a node.
+       */
       updateNodeAttributes,
+      /**
+       * Wrap a node in a list.
+       */
       wrapInList,
     }
   },

packages/extension-blockquote/src/index.ts

@@ -24,6 +24,9 @@ const Blockquote = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a blockquote node
+       */
       blockquote: (): Command => ({ commands }) => {
         return commands.toggleWrap('blockquote')
       },

packages/extension-bold/src/index.ts

@@ -33,7 +33,7 @@ const Bold = createMark({
   addCommands() {
     return {
       /**
-       * bold command
+       * Toggle a bold mark
        */
       bold: (): Command => ({ commands }) => {
         return commands.toggleMark('bold')

packages/extension-bullet-list/src/index.ts

@@ -22,6 +22,9 @@ const BulletList = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a bullet list
+       */
       bulletList: (): Command => ({ commands }) => {
         return commands.toggleList('bulletList', 'listItem')
       },

packages/extension-code-block/src/index.ts

@@ -70,6 +70,9 @@ const CodeBlock = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a code block
+       */
       codeBlock: (attrs?: CodeBlockOptions): Command => ({ commands }) => {
         return commands.toggleBlockType('codeBlock', 'paragraph', attrs)
       },

packages/extension-code/src/index.ts

@@ -22,6 +22,9 @@ const Code = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle inline code
+       */
       code: (): Command => ({ commands }) => {
         return commands.toggleMark('code')
       },

packages/extension-collaboration-cursor/src/index.ts

@@ -30,6 +30,9 @@ const CollaborationCursor = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Update details of the current user
+       */
       user: (attributes: {
         name: string,
         color: string,

packages/extension-font-family/src/index.ts

@@ -37,6 +37,9 @@ const FontFamily = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Update the font family
+       */
       fontFamily: (fontFamily: string | null = null): Command => ({ chain }) => {
         return chain()
           .updateMarkAttributes('textStyle', { fontFamily })

packages/extension-hard-break/src/index.ts

@@ -22,6 +22,9 @@ const HardBreak = createNode({
 
   addCommands() {
     return {
+      /**
+       * Add a hard break
+       */
       hardBreak: (): Command => ({ commands, state, dispatch }) => {
         return commands.try([
           () => exitCode(state, dispatch),

packages/extension-heading/src/index.ts

@@ -49,7 +49,7 @@ const Heading = createNode({
   addCommands() {
     return {
       /**
-       * heading command
+       * Toggle a heading node
        */
       heading: (options: { level: Level }): Command => ({ commands }) => {
         if (!this.options.levels.includes(options.level)) {

packages/extension-highlight/src/index.ts

@@ -48,6 +48,9 @@ const Highlight = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle a highlight mark
+       */
       highlight: (attributes?: { color: string }): Command => ({ commands }) => {
         return commands.toggleMark('highlight', attributes)
       },

packages/extension-history/src/index.ts

@@ -14,9 +14,15 @@ const History = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Undo recent changes
+       */
       undo: (): Command => ({ state, dispatch }) => {
         return undo(state, dispatch)
       },
+      /**
+       * Reapply reverted changes
+       */
       redo: (): Command => ({ state, dispatch }) => {
         return redo(state, dispatch)
       },

packages/extension-horizontal-rule/src/index.ts

@@ -17,6 +17,9 @@ const HorizontalRule = createNode({
 
   addCommands() {
     return {
+      /**
+       * Add a horizontal rule
+       */
       horizontalRule: (): Command => ({ tr }) => {
         tr.replaceSelectionWith(this.type.create())
 

packages/extension-image/src/index.ts

@@ -51,6 +51,9 @@ const Image = createNode({
 
   addCommands() {
     return {
+      /**
+       * Add an image
+       */
       image: (options: { src: string, alt?: string, title?: string }): Command => ({ tr }) => {
         const { selection } = tr
         const node = this.type.create(options)

packages/extension-italic/src/index.ts

@@ -31,6 +31,9 @@ const Italic = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle an italic mark
+       */
       italic: (): Command => ({ commands }) => {
         return commands.toggleMark('italic')
       },

packages/extension-link/src/index.ts

@@ -45,6 +45,9 @@ const Link = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle or update a link mark
+       */
       link: (options: { href?: string, target?: string } = {}): Command => ({ commands }) => {
         if (!options.href) {
           return commands.removeMark('link')

packages/extension-ordered-list/src/index.ts

@@ -41,6 +41,9 @@ const OrderedList = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle an ordered list
+       */
       orderedList: (): Command => ({ commands }) => {
         return commands.toggleList('orderedList', 'listItem')
       },

packages/extension-paragraph/src/index.ts

@@ -20,6 +20,9 @@ const Paragraph = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a paragraph
+       */
       paragraph: (): Command => ({ commands }) => {
         return commands.toggleBlockType('paragraph', 'paragraph')
       },

packages/extension-strike/src/index.ts

@@ -31,6 +31,9 @@ const Strike = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle a strike mark
+       */
       strike: (): Command => ({ commands }) => {
         return commands.toggleMark('strike')
       },

packages/extension-task-list/src/index.ts

@@ -22,6 +22,9 @@ const TaskList = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a task list
+       */
       taskList: (): Command => ({ commands }) => {
         return commands.toggleList('taskList', 'taskItem')
       },

packages/extension-text-align/src/index.ts

@@ -34,6 +34,9 @@ const TextAlign = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Update the text align attribute
+       */
       textAlign: (alignment: string): Command => ({ commands }) => {
         if (!this.options.alignments.includes(alignment)) {
           return false

packages/extension-text-style/src/index.ts

@@ -26,6 +26,9 @@ const TextStyle = createMark({
 
   addCommands() {
     return {
+      /**
+       * Remove spans without inline style attributes.
+       */
       removeEmptyTextStyle: (): Command => ({ state, commands }) => {
         const attributes = getMarkAttrs(state, this.type)
         const hasStyles = Object.entries(attributes).every(([, value]) => !!value)