fix: Cover distinction from this and comments

This commit is contained in:
Ed Page 2023-10-03 20:30:19 -05:00
parent 5479104a03
commit 7bcaca9e84
1 changed files with 6 additions and 0 deletions

View File

@ -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