The text shown in the Snippet Generator for the parallel step explains the syntax and notes that mechanical generation of snippets is not available in this case. I am not sure what else there is to do. This is a special step in that it is engine-specific and has a syntax outside the normally permitted scope.

This is what I see in the snippet generator help text:

(No visual configuration.) Takes a map from branch names to closures 
and an optional argument failFast which will terminate all branches upon a failure in any other branch:

parallel firstBranch: {
    // do something
}, secondBranch: {
    // do something else
},
failFast: true|false

IMO it's not clear that the snippet generator will fail. If this is an accepted behaviour, I will note it clearly in the help text (as I'm currently working on JENKINS-30086).

No visual configuration.

is what I meant, but yes it could be better explained.

ParallelStep.DescriptorImpl could override newInstance(StaplerRequest, JSONObject) to return some sample ParallelStep with no branches, but this is not very helpful. Might be better for this to throw something (UnsupportedOperationException?) that would be rendered more politely in the result textarea, or even for StepDescriptor to be allowed to state that it has no visual configuration and to simply disable the snippet generation button in that case.

pipeline-syntax/html shows this error instead of documentation.

This also affects GDSL files generated by Jenkins:

// Errors on:
// class org.jenkinsci.plugins.workflow.cps.steps.ParallelStep: There's no @DataBoundConstructor on any constructor of class org.jenkinsci.plugins.workflow.cps.steps.ParallelStep

Also affects https://jenkins.io/doc/pipeline/steps/workflow-cps/#parallel-execute-in-parallel

The issue still exists on the latest versions

 I added the following lines to the GDSL and it seems to be working, using Intellij IDEA (2017.2.5):

method(name: 'parallel', type: 'Object', params: [steps: 'Map'], doc: 'Execute in parallel')
method(name: 'parallel', type: 'Object', params: [steps: 'Map', failFast: 'boolean'], doc: 'Execute in parallel')

Another workaround, is to just disable the check by adding the following comment above each call to parallel:

//noinspection GroovyAssignabilityCheck

But this is really just ignoring the issue, and unhelpful for autocomplete / syntax highlighting.

I filed a PR to fix the GDSL issue here. The snippet generator and automatically generated documentation would not be affected by that PR.

Ok, the GDSL issues should be fixed in Pipeline: Groovy Plugin version 2.73. The documentation issues and error when "generate snippet" is clicked still exist, and I'm not sure of a good way to fix them without more special casing for the parallel step. I'm going to move this back to open.