Support multiline graphql descriptions (Fix #2405)

[AlexMabry]

I took a stab at this, hoping to save you some time.

[RunDevelopment]

Thank you @AlexMabry for this PR!

To make the CI pass, you have to rebuild Prism using the command npx gulp.

Before we merge this, we also have to talk about whether we want Markdown highlighting inside multiline strings. You added this because they are frequently used for this purpose (I assume) but 1) single-line strings may also be used for descriptions and 2) multi-line strings may not contain Markdown if used as values.

Here is my suggestion on how we could do this:

'description': {
	pattern: /(?:"""(?:[^"]|(?!""")")*"""|"(?:\\.|[^\\"\r\n])*")(?=\s*[a-z_])/i,
	greedy: true,
	alias: 'string',
	inside: {
		// TODO: Exclude leading and trailing "
		'language-markdown': {
			pattern: /[\s\S]+/,
			inside: Prism.languages.markdown
		}
	}
},
'string': {
	pattern: /"""(?:[^"]|(?!""")")*"""|"(?:\\.|[^\\"\r\n])*"/,
	greedy: true
},

The basic idea is that a description is always followed by either a keyword or a name (see grammar), so the (?=\s*[a-z_]) lookahead should be enough to differentiate description strings and (value) strings.

Thoughts?
(I don't use GraphQL, so I don't know whether there are some cases for which this doesn't work.)

(I also had to slightly change the multi-line string pattern because of the lookahead (see lazy trap).)

[mAAdhaTTah]

Also, if Markdown is optional, I think it needs to be added to the language conditionally.

[RunDevelopment]

@mAAdhaTTah I think it's totally fine to have a language-markup wrapper around markdown without highlighting. The token stream is more stable that way compared to if we were to only conditionally add the language-markup or even description token.

[AlexMabry]

@RunDevelopment Thanks for the suggestions. I agree with you that descriptions and strings should be treated differently.

After making your change, I also made the additional changes:

• components/
  • Changed the alias for descriptions from 'string' to 'comment' which I think is more appropriate
• examples/
  • Updated the string and description examples
• tests/languages/graphql/
  • Added a multi-line string test
  • Added some basic description tests
• tests/languages/markdown+graphql/
  • Added a description test that checks markdown in descriptions

It looks likes CI is still failing, so I will look into that

[RunDevelopment]

Thank you for making the changes @AlexMabry.

Tests and examples look good but two more things.

First, string vs comment. I can see why you changed it to comment. Most popular languages use comments for documentation (e.g. C++, Java, JS) while only a few use strings (e.g. Python).
However, I think it should still be highlighted as string. The spec and many articles I found refer to them as descript (or documentation) strings. Since people seem to think about them as strings (similar to Python), I think we should also highlight them as such.

Second, please see the below comment on leading and trailing quotes.

[RunDevelopment]

Now the only remaining question is: How do we handle this?
I want to exclude the leading and trailing quotes because some of Markdown's features are line-based and therefore might consume the trailing quotes.

I think that this solution is kinda dumb but it'll work:

Suggested change

	// TODO: Exclude leading and trailing "
	'language-markdown': {
	pattern: /[\s\S]+/,
	'language-markdown': {
	pattern: /(^"(?:"")?)(?!\1)[\s\S]+(?=\1$)/,
	lookbehind: true,

The basic idea is to use a backreference to exclude the same number of leading and trailing quotes. The (?!\1) lookahead will then ensure that an empty multi-line string will not have a language-markdown token.

This is the only correct solution I can think of but it's not obvious or elegant. Does anybody have a simpler solution for this?

[AlexMabry]

I just made the changes that you recommended.

[RunDevelopment]

Thank you very much for contributing @AlexMabry!