README.md

@@ -136,7 +136,7 @@ read replaces mentions, attachments and macros with text.
 - A newline in text is a hard break and in an expand's title a space, edge whitespace outside a
   link or code span is trimmed, carriage returns and null characters are removed, and an empty
   paragraph drops.
-- A text node's `content`, which Atlassian's schema forbids, drops.
+- A text node's `content` drops: Atlassian's schema forbids it, so no rendered document shows it.
 - An ordered list numbered past `999999999`, or adjacent ordered lists whose numbering does not
   continue, is one bullet list keeping its numbers as text.
 - A task list beside a bullet or decision list, or holding a block other than a task, joins one

src/markdown/plain/editor-normal.ts

@@ -7,7 +7,7 @@ type JsonContainer = JsonValue[] | { [key: string]: JsonValue }
 
 type NodeHolder = { content?: AdfNode[] }
 
-// The editor's rule is the reader's over the pair's editor-normal forms.
+// The editor joins two text nodes where the reader would join their editor-normal forms.
 export function joinsWhenEditorNormal(previous: AdfNode, node: AdfNode): boolean {
   if (previous.type !== 'text' || node.type !== 'text') return false
   return joinsWhenRead(normalNode(previous), normalNode(node))
@@ -25,7 +25,7 @@ export function toEditorNormal(document: AdfDocument): AdfDocument {
     if (content.length === 0) continue
     entry.holder.content = content.map((source) => {
       const holder = normalNode(source)
-      // Atlassian's schema allows a text node no content, so the editor keeps none.
+      // Atlassian's schema forbids content on a text node, so the editor drops it.
       if (source.type !== 'text') pending.push({ holder, source })
       return holder
     })