Add clarifying comments for escaping html

Author: andrew-polk

src/pull.ts

@@ -281,6 +281,15 @@ function escapeHtml(block: any): void {
       const rt = blockContent.rich_text[i];
 
       // See https://github.com/sillsdev/docu-notion/issues/21.
+      // For now, we just do a simple replace of < an > with &lt; and &gt;
+      // but only if the text will not be displayed as code.
+      // If it will be displayed as code,
+      // a) nothing will be trying to parse it, so it is safe.
+      // b) at no point does anything interpret the escaped character **back** to html;
+      //    so it will be displayed as "&lt;" or "&gt;".
+      // We may have to add more complex logic here in the future if we
+      // want to start letting html through which we **do** want to parse.
+      // For example, we could assume that text in a valid html structure should be parsed.
       if (
         rt?.plain_text &&
         block.type !== "code" &&