From 7bcaca9e84ff1e1aeed3e9dd5da88a06e737142a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 3 Oct 2023 20:30:19 -0500 Subject: [PATCH] fix: Cover distinction from this and comments --- text/3503-frontmatter.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/text/3503-frontmatter.md b/text/3503-frontmatter.md index 3b5d1afe2..37943ba7a 100644 --- a/text/3503-frontmatter.md +++ b/text/3503-frontmatter.md @@ -130,6 +130,11 @@ However, a new syntax is used instead of extending the comment syntax: user expectations with the looseness of comment syntax (which supporting would make it harder to parse) and any existing comments that may look like a new structured comment syntax +The difference between this syntax and comments is comments are generally +geared towards people, even if a subset (doc-comments) are also able to be +somewhat processed by a program, while this is geared mostly towards machine +processing. + This proposal mirrors the location of YAML frontmatter (absolutely first). As we learn more of its uses and problems people run into in practice, we can evaluate if we want to loosen any of the rules. @@ -147,6 +152,7 @@ Benefits: Downsides: - When sharing in markdown documents (e.g. GitHub issues), requires people escape markdown code fences with an extra backtick which they are likely not used to doing (or aware even exists) - Familiar syntax in an unfamiliar use may make users feel unsettled, unsure how to proceed (what works and what doesn't). +- If viewed from the lens of a comment, it isn't a variant of comment syntax like doc-comments ### Alternative 1: Doc-comment