Three dot ellipses used for both comments and spread operators is confusing

[Fosten]

@jackahl I brought this up during the PloneConf21 Trainings OpenSpace and @fredvd asked me to make a ticket. When using ... as a comment, recommend using // ... (and perhaps some text) to make it more apparent this is actually a comment. Looks like most of the training pages do this already, but there are a few occurrences in places like https://training.plone.org/5/voltohandson/header.html#header-component without the double slash. I've found this to be more prevalent on the https://docs.voltocms.com site which I'm not sure falls under this issue tracker. But on pages where there is both a ... comment and a ... spread operator, this can be particularly confusing.

export blocks = {
...config.blocks,
}
...

[stevepiercy]

The Training docs are separate from the Volto docs and follow different style guides.

From the Training's Authors Guide, under Syntax Highlighting:

The snippet must be valid syntax for the language you specify, else it will not be highlighted properly. Avoid adding comments to code snippets, unless you use valid comment syntax for that language. For example, JSON does not allow comments.

Do not indicate elided or omitted code with ellipses (... or …). These are almost never valid syntax and will cause syntax highlighting to fail for the code block.

When a PR comes through for this issue, I would change that to:

Do not indicate elided, omitted, or commented code with ellipses (... or …). These are almost never valid syntax and will cause syntax highlighting to fail for the code block. An exception is the JavaScript spread operator, which consists of three consecutive dots (...). It is valid JavaScript code. If ellipses are used as elided code in comments, they can be confused with the JavaScript spread operator. Please do not use ellipses in comments.

As an alternative, consider using code blocks with linenos, emphasize-lines, lineno-match, or dpatch as a lexer.

I would appreciate a PR that follows these guidelines.