Docs

[waterlink]

refs #189

This PR adds proper aruba/cucumber/relish setup for alive documentation through BDD.

• few documented pages.

@egonSchiele you probably need access to those publishers I have created on relish:

• https://relishapp.com/contracts-staging
• https://relishapp.com/contracts

For that, can you signup (if you haven't already) on https://relishapp.com/ and send me your relish username (here or by email)?

Relish was chosen because of impression created by rspec's team documentation there. It really looks good and offers nice features.

This PR does not add all the documentation yet, but it would be nice to get this reviewed, code-review-fixed and merged, so that we can go in small increments with this.

How it would look when released can be seen at https://relishapp.com/contracts-staging and https://relishapp.com/contracts-staging/contracts-ruby

Cheers!

[waterlink]

PR is quite big. Might make more sense to review it by one commit at a time.

[egonSchiele]

Thanks for doing this @waterlink ! I'll make an account and take a look soon.

[egonSchiele]

@waterlink my username is adit.

[waterlink]

I have added you to these publishers. You should be able to see them at your dashboard at https://relishapp.com/my/publishers

[waterlink]

BTW, @egonSchiele Can you take a look at a PR, and how it looks on staging publisher? It is important to merge that, because after that multiple small documentation changes can be done in parallel in their respective *.feature files, even by multiple contributors! - which is awesome :)

Anybody else wants to review? /cc @sfcgeorge @nixpulvis

[waterlink]

Don't be afraid of +1537, -0. It is documentation - pure markdown text and a bit of code examples (not spaghetti code that needs to be understood :D )

[waterlink]

/cc @dg-ratiodata You might want to take a look as well and tell if I have utilized aruba correctly in your opinion.

[egonSchiele]

I would suggest a less complicated function, or just remove this one...two examples is enough.

[egonSchiele]

Ah, I guess you want the third example as the singleton example. Maybe def increment(x); x + 1; end ?

[alex-fedorov]

Will change it now.

[alex-fedorov]

added commit on top of master: 51cfe7c

[egonSchiele]

This is really cool @waterlink, thanks for doing it.

[ghost]

Is that really something "normal" end users are going to use? Otherwise I would move that to "features/developers/..." or something similar.

[alex-fedorov]

Makes sense to move it to features/developers/functype.feature I think.

[ghost]

@waterlink I think you're on a very good way. :-)

What I found out while "writing" our documentation:

1. Concentrate on API which is relevant to your users
2. Write the tests in a way you expect your users to use the API
3. Some edge case might be better documented by Rspec or something similar and is not exposed to your users

Something I tend to do:

• Combine cucumber and rspec for documentation - example: https://github.com/cucumber/aruba/blob/master/features/api/command/run.feature, this step will be part of the upcoming aruba release. For now you need to copy the relevant lines from this file.

Something like that - not tested.

Scenario: No Instance method contract violation
  Given a file named "contract.rb" with:
  """ruby
  require "contracts"
  C = Contracts

  class Example
    include Contracts::Core

    Contract C::Num, C::Num => C::Num
    def add(a, b)
      a + b
    end
  end
  """
  And a file named "spec/instance_method_violation_spec.rb" with:
  """
  require 'contract.rb'

  RSpec.describe "instance method violation" do
    subject { Example.new }

    let(:a) { 1 }
    let(:b) { 2 }

    it { expect(subject.add(a, b)).to eq 3 }
  end
  """
  When I run `rspec`
  Then the specs should all pass

Scenario: Instance method contract violation
  Given a file named "contract.rb" with:
  """ruby
  require "contracts"
  C = Contracts

  class Example
    include Contracts::Core

    Contract C::Num, C::Num => C::Num
    def add(a, b)
      a + b
    end
  end
  """
  And a file named "spec/instance_method_violation_spec.rb" with:
  """
  require 'contract.rb'

  RSpec.describe "instance method violation" do
    subject { Example.new }

    let(:a) { 1 }
    let(:b) { 'a' }

    it { expect { subject.add(a, b) }.to raise_error ParamContractError }
  end
  """
  When I run `rspec`
  Then the specs should all pass

Using this approach you do not need to do something like puts XY but you can use the same "synatx" your users are using.

Hope this makes sense to you.

[sfcgeorge]

Oh this is pretty cool, nice!

[alex-fedorov]

@dg-ratiodata For contract violation errors I wanted to demonstrate exactly how error looks like and what data it has inside. How would you do that with RSpec ?

[ghost]

Oh, ok. But what about something like that:

let(:error_message) { <<-EOS
    : Contract violation for argument 2 of 2: (ParamContractError)
            Expected: Num,
            Actual: "foo"
            Value guarded in: Example::add
            With Contract: Num, Num => Num
            At: instance_method_violation.rb:8
EOS
}

it { expect { subject.add(a, b) }.to raise_error ParamContractError,  error_message }

[waterlink]

That sounds good. I will try it out. Thanks! :)

Best Regards,
Alexey Fedorov,
Sr Ruby, Clojure, Crystal, Golang Developer,
Microservices Backend Engineer,
+49 15757 486 476

2015-09-08 9:27 GMT+02:00 Dennis Günnewig notifications@github.com:

Oh, ok. But what about something like that:

let(:error_message) { <<-EOS : Contract violation for argument 2 of 2: (ParamContractError) Expected: Num, Actual: "foo" Value guarded in: Example::add With Contract: Num, Num => Num At: instance_method_violation.rb:8EOS
}

it { expect { subject.add(a, b) }.to raise_error ParamContractError, error_message }

—
Reply to this email directly or view it on GitHub
#195 (comment)
.