Add a couple section headers in language overview doc #5175
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I added mention of the Zed language
//
comment syntax back in #4308 after a community user reported not realizing this concept existed (#4302). Another community user just pointed out via #4310 (comment) that the way it's covered in the docs now doesn't currently bubble up nicely in the search results. I'm not 100% certain if their proposed change of adding a section header would improve that, but rather than investing time into setting up a test sandbox to investigate, I spent some time re-reading the page to see if adding a header makes sense regardless.Looking at it through that lens, indeed, I can see that the coverage as it's been feels a little "tacked on", but I was always had trouble coming up with a better idea. Having a wholly separate page under "Language" at the same level as "Expressions", "Operators" etc. just to briefly mention comments feels like overkill. I also don't see a different existing page into which it would graft nicely as a header-worthy section, though I'm open to suggestion.
The "Overview" page should surely be brief, so I respect the urge to avoid lots of section headers there. However, I did ultimately find that adding a "Search and Analytics" header feels pretty natural to me, so once I've got that, the header for Comments feels a bit more natural, too.
As for the user's point in #4302 about if we should divulge the gotcha here about multi-line
/* */
comment syntax being available in ZSON but not Zed language, I'm holding off on that for the moment in hopes it might be easier to just enhance the parser. 🤞