Gherkin multline comments #203

Closed
rmpestano opened this Issue Apr 7, 2016 · 10 comments

Comments

Projects
None yet
2 participants

There is a way to have multline comments in feature files?

If not, there is any plan to support it?

We are using comments to 'enhance' JSON formmat output to later generate the living documentation.

Thanks in advance.

Owner

aslakhellesoy commented Apr 7, 2016

The only supported comment format is single line comments using #.

We'll never support multiline comments like /* */ because comments in gherkin is something that should be avoided.

Hi @aslakhellesoy, thank you for the answer.

There is any way I can extend gherkin parser in cucumber-java so it would allow multiline comments?

Owner

aslakhellesoy commented Apr 8, 2016

@rmpestano yes, it's open source, so you can do what you want with it.

Sure, thats the main reason we are here ;)

Any hint on where to start? I don't want to build my on cucumber distribution. Some extension point/interface I can implement? Something like ObjectFactory but for gherkin parser?

Owner

aslakhellesoy commented Apr 8, 2016

I strongly suggest you don't go down this rabbit hole.

Cucumber-JVM is currently based on Gherkin2 and will sooner or later move to Gherkin3+.

You'd have to modify Gherkin2's Ragel grammar and rebuild it. When Cucumber-JVM moves to Gherkin3+ you'd have to re-implement your changes. In the meanwhile you'd be building up non-standard Gherkin documents that won't work anywhere else than with your proprietary fork of the Gherkin parser. That's probably going to cause you a lot of problems. No other Gherkin based tools will work with your features.

This sounds like an XY Problem to me. You think the solution to your problem is multiline comments.

If you explain why you think you need multiline comments I think I'll be able to convince you they are a really bad idea in the first place.

About the 'why' the multiline its because i'm using comments to enhance the living documentation. This 'enhancement' can be done using asciidoc syntax and would be easier to be done in multiline comments.

Here is a sample: https://github.com/rmpestano/cukedoctor#sample

The comment thing is just to provide additional information. Not a big thing cause the comments are not executed by tests and then can be outdated.

Owner

aslakhellesoy commented Apr 10, 2016

Why don't you just write this asciidoc prose in the description section?

Feature: a
  Some text
  here

  Scenario: b
    Here is
    some more
    text

    Given d

Yea, that's already possible. The comments are for steps level, example:

Feature: a
  Some text
  here

  Scenario: b
    Here is
    some more
    text

    # comment with asciidoc markup will be rendered after step as additional step information in living documentation
    Given d

The ideia behind this 'additional step information' is that we keep steps as simple sentences and if you want to give more context information you can do via comments on the step.

Of course there are ways to provide more information like breaking the step into more steps or even scenarios but maybe a bit more of context can help clarify whats being executed by the step.

See the When step of this feature: http://rmpestano.github.io/cukedoctor/cukedoctor-documentation.html#_scenario_convert_features_test_output_into_documentation

it says:

When 
I convert cucumber json test output using cukedoctor converter 

and the additional step info is saying how to generate those json output

Owner

aslakhellesoy commented Apr 10, 2016

I think that in general, steps should be self-explanatory. Ideally we don't want comments in Gherkin at all. If we add support for multiline comments we're implicitly encouraging people to add more comments by making it easier for people to do.

Sorry - it's not going to happen.

That's fine, in general I also think its not a good idea. I will find a way for my usecase.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment