Add a comment describing each plugin

src/plugins/bibliography.ts

@@ -69,6 +69,10 @@ interface Props {
   getManuscript: GetManuscript
 }
 
+/**
+ * This plugin generates labels for inline citations and the bibliography contents, using citeproc-js.
+ * The citation labels and bibliography are regenerated when any relevant content changes.
+ */
 export default (props: Props) => {
   const buildDecorations = (
     doc: ManuscriptNode,
@@ -166,6 +170,8 @@ export default (props: Props) => {
           props.getManuscript
         )
 
+        // TODO: return the previous state if nothing has changed, to aid comparison?
+
         return {
           citationNodes,
           citations,

src/plugins/elements.ts

@@ -18,6 +18,11 @@ import { ManuscriptSchema } from '@manuscripts/manuscript-transform'
 import { Plugin } from 'prosemirror-state'
 import { Decoration, DecorationSet } from 'prosemirror-view'
 
+/**
+ * This plugin simply sets `element: true` in a Decoration spec for each element (a non-section node that is a child of a section).
+ * `createNodeOrElementView` uses this to decide whether to create a NodeView or just a regular DOM element.
+ * This is useful for paragraphs and lists, for example, which may be nested inside top-level elements of the same node type.
+ */
 export default () => {
   return new Plugin<null, ManuscriptSchema>({
     props: {

src/plugins/highlight.ts

@@ -175,6 +175,9 @@ interface Props {
   setCommentTarget: (target?: string) => void
 }
 
+/**
+ * This plugin creates a decoration around each highlight marker start and end pair, and keeps a map of all the highlights.
+ */
 export default (props: Props) => {
   return new Plugin<HighlightPluginState, ManuscriptSchema>({
     key: highlightKey,

src/plugins/keywords.ts

@@ -58,6 +58,9 @@ interface Props {
   getModel: <T extends Model>(id: string) => T | undefined
 }
 
+/**
+ * This plugin updates the contents of a Keywords element in the document (if present) when keywords are modified in the manuscript metadata.
+ */
 export default (props: Props) => {
   return new Plugin<undefined, ManuscriptSchema>({
     key: keywordsKey,

src/plugins/models.ts

@@ -29,6 +29,9 @@ interface Props {
   deleteModel: (id: string) => Promise<string>
 }
 
+/**
+ * This plugin allows commands that don't otherwise have access to the database to insert, remove or update models, by dispatching the model in a transaction.
+ */
 export default (props: Props) => {
   return new Plugin<Record<string, unknown>, ManuscriptSchema>({
     key: modelsKey,

src/plugins/objects.ts

@@ -37,6 +37,9 @@ interface Props {
   getModel: <T extends Model>(id: string) => T | undefined
 }
 
+/**
+ * This plugin sets the labels for cross-references, and adds the label as a decoration to cross-referenceable elements.
+ */
 export default (props: Props) => {
   return new Plugin<Map<string, Target>, ManuscriptSchema>({
     key: objectsKey,

src/plugins/paragraphs.ts

@@ -21,6 +21,9 @@ import {
 } from '@manuscripts/manuscript-transform'
 import { Plugin } from 'prosemirror-state'
 
+/**
+ * This plugin enforces a rule that there can never be more than one adjacent empty paragraph.
+ */
 export default () => {
   return new Plugin<null, ManuscriptSchema>({
     appendTransaction: (transactions, oldState, newState) => {

src/plugins/persist.ts

@@ -22,6 +22,9 @@ import {
 } from '@manuscripts/manuscript-transform'
 import { Plugin } from 'prosemirror-state'
 
+/**
+ * This plugin ensures that all nodes which need ids (i.e. `id` is defined in the node spec's attributes) are given an id, and that there aren't any duplicate ids in the document.
+ */
 export default () => {
   return new Plugin<null, ManuscriptSchema>({
     appendTransaction: (transactions, oldState, newState) => {

src/plugins/placeholder.ts

@@ -40,6 +40,9 @@ const placeholderWidget = (placeholder: string) => (
   return element
 }
 
+/**
+ * This plugin adds a placeholder decoration to empty nodes
+ */
 export default () =>
   new Plugin<null, ManuscriptSchema>({
     props: {

src/plugins/sections.ts

@@ -20,6 +20,9 @@ import {
 } from '@manuscripts/manuscript-transform'
 import { Plugin } from 'prosemirror-state'
 
+/**
+ * This plugin ensures that every section contains at least one child element, inserting a paragraph element after the title if needed.
+ */
 export default () => {
   return new Plugin<null, ManuscriptSchema>({
     appendTransaction: (transactions, oldState, newState) => {

src/plugins/styles.ts

@@ -45,6 +45,9 @@ interface Props {
   modelMap: Map<string, Model>
 }
 
+/**
+ * This plugin ensures that all nodes are given default styles where needed, according to the attributes defined in the node spec.
+ */
 export default (props: Props) => {
   const chooseDefaultFigureStyle = (): string | undefined => {
     for (const model of props.modelMap.values()) {

src/plugins/toc.ts

@@ -139,6 +139,9 @@ interface Props {
   modelMap: Map<string, Model>
 }
 
+/**
+ * This plugin generates the content for a Table of Contents element, if present
+ */
 export default (props: Props) => {
   return new Plugin<null, ManuscriptSchema>({
     key: tocKey,