Update comments

super_editor_markdown/lib/src/document_to_markdown_serializer.dart

@@ -364,11 +364,13 @@ class AttributedTextMarkdownSerializer extends AttributionVisitor {
   }
 }
 
-/// [DocumentNodeMarkdownSerializer] for serializing [ParagraphNode]s as headers.
+/// [DocumentNodeMarkdownSerializer], which serializes Markdown headers to
+/// [ParagraphNode]s with an appropriate header block type, and (optionally) a
+/// block alignment.
 ///
-/// We already had a header parser in [ParagraphNodeSerializer] but without the alignment,
-/// so we added [HeaderNodeSerializer] to support the alignment for headers. Therefore,
-/// the [HeaderNodeSerializer] **MUST** be put before the [ParagraphNodeSerializer].
+/// Headers are represented by `ParagraphNode`s and therefore this serializer must
+/// run before a [ParagraphNodeSerializer], so that this serializer can process
+/// header-specific details, such as header alignment.
 class HeaderNodeSerializer extends NodeTypedDocumentNodeMarkdownSerializer<ParagraphNode> {
   const HeaderNodeSerializer(this.markdownSyntax);
 

super_editor_markdown/lib/src/markdown_to_document_parsing.dart

@@ -700,9 +700,9 @@ class _TaskSyntax extends md.BlockSyntax {
 
 /// Parses a header preceded by an alignment token.
 ///
-/// We already had a header serializer in [_ParagraphWithAlignmentSyntax] but without the alignment,
-/// so we added [_HeaderWithAlignmentSyntax] to support the alignment for headers. Therefore,
-/// the [_HeaderWithAlignmentSyntax] **MUST** be put before the [_ParagraphWithAlignmentSyntax].
+/// Headers are represented by `_ParagraphWithAlignmentSyntax`s and therefore
+/// this parser must run before a [_ParagraphWithAlignmentSyntax], so that this parser
+/// can process header-specific details, such as header alignment.
 class _HeaderWithAlignmentSyntax extends md.BlockSyntax {
   /// This pattern matches the text alignment notation.
   ///