Data table and Doc string are not documented as mutually exclusive about docs HOT 6 OPEN

I'm not privy the original reason for preventing the use of doc strings and data tables together. But looking back that decision seems to have been intentional.

For example in cucumber/cucumber-jvm#1183 I do see that the Gherkin v2.12.2 accepted the combination. Though it did cause an error in Cucumber JVM.

And looking at cucumber-attic/gherkin2#138 being able to parse any combination of docstrings and data tables (and incorrectly assign it to the wrong step) was considered a bug in Gherkin v2 in 2011 already.

I suspect the complexity of dealing with both docstring and data tables together in dynamically typed languages is was considered to be too much at the time.

@brasmusson @aslakhellesoy do you have anything to add to that?

In some cases it's really useful.

Such as?

Moreover, it works with quite a lot of cucumber-runners, JetBrains plugin also marks such syntax as valid.

Do you have a list of runners? I'm curious to see how they behave.

from docs.

In some cases it's really useful.

Such as?

Well, can't imagine all ways to use it, but even taking example from reference it can be combined. Let's take a look at:

It could be something like User sends a message to:, where content of DocString is a message and DataTable is kinda "mailing list"

Or, for example, DocString is SQL and DataTable contains sources to select.

It can be done by splitting to different steps ofc, but it would require to handle more states and preserve data for following steps.

from docs.

Moreover, it works with quite a lot of cucumber-runners, JetBrains plugin also marks such syntax as valid.

Do you have a list of runners? I'm curious to see how they behave.

I currently mostly work with rust runner (unofficial) as I mentioned above, it works like a charm to me.
It's possible to work with gherkin::Step which can have both docstring and table at the same time.

Sorry, I think "quite a lot" was too strong claim, at least for now - when I checked impls in this repo.
I can’t remember when and what kind of runner that was, but this syntax worked in another implementation (could be specific period of time?).
Therefore, perhaps I had a false feeling that this is allowed (also taking into account plugin highlighting and auto-formatting over all the time)

from docs.

Just to clarify: I'm totally ok if it's disallowed by intention.

Would be nice to consider allowing this or explicitly mention in documentation it's invalid gherkin syntax

from docs.

It is a complicated question.

Gherkins grammar is specified in Berp. And in that grammar, doc strings and data tables are mutually exclusive:

https://github.com/cucumber/gherkin/blob/24952f9ad5b90d6f3df2e0868e932a9c519a767e/gherkin.berp#L27-L28

But Berp is only used for Gherkin. So there is effectively no technical specification to violate. You could still ask the cucumber-rs team to match the behavior of the Cucumber Gherkin parser though.

As for IDEA. the Gherkin syntax is not versioned and has had some breaking changes over time. So it is not surprising their parser supports a superset of the different versions of Gherkin.

from docs.

If you want to update the docs, the sentence:

In some cases you might want to pass more data to a step than fits on a single line. For this purpose Gherkin has Doc Strings and Data Tables.

Could be rewritten to more strongly suggest they're mutually exclusive. Not too technically though, these are end user documentation, not technical specifications. Something like (though I think it is a bit repetitive, repeating the you every sentence):

In some cases you might want to pass more data to a step than fits on a single line. For this purpose you can either use Doc Strings or Data Tables.

We take pull requests for the docs at: https://github.com/cucumber/docs

If you want to send one that would be nice, if not I can move this whole issue there.

from docs.