From dchelimsky at gmail.com  Fri Nov  6 07:49:10 2009
From: dchelimsky at gmail.com (David Chelimsky)
Date: Fri, 6 Nov 2009 07:49:10 -0500
Subject: [rspec-devel] describe "RSpec's documentation" do
Message-ID: <A3756A49-A10C-4138-8665-AAB730556A2B@gmail.com>

Hi all,

describe "RSpec's documentation" do
   it "should be helpful"
   it "should be maintainable"
end

I've been wanting to improve RSpec's documentation situation for a  
long time, but my writing energies have been consumed by rspec itself  
and The RSpec Book for a longer time, and will continue to do so for  
the foreseeable future. So I'm going to need some help.

The problem to solve is that we have (at least) four sources of  
documentation, each of which moves at its own pace and has evolved in  
its meaning/place:

1. The RSpec code examples that ship with RSpec
2. The Cucumber features that ship with RSpec
3. The github wiki: http://wiki.github.com/dchelimsky/rspec
4. http://rspec.info

The model that Aslak and the Cucumber community has used has worked  
very well because it's a community effort, but there is still some  
duplication between what's on the wiki [1] and the Cucumber features/ 
scenarios that ship with Cucumber [2].

In the long run, what I'd like is the following:

* Cucumber features that ship with RSpec become the authoritative end- 
user documentation. This is something that anybody can contribute to  
with patches, as it's all in files that ship with RSpec. I'd also like  
to use such an effort to push the envelope on Cucumber features as  
executable documentation. I think that with a little bit of work we  
could use the features to generate a website with meaningful  
organization/navigation. Is anybody already doing that?
* RSpec code examples become a solid source of additional detailed  
documentation for those who want to either extend RSpec or debug  
problems.
* http://rspec.info becomes a one pager like http://cukes.info
* The github wiki becomes a community driven resource center with  
links to tutorials, blogs, matcher libraries, etc, etc

I welcome suggestions, but I really need volunteers volunteers! I'm  
not going to be able to spend much personal time on this, so if there  
are any among you who are willing to coordinate with me and drive the  
effort, I'd love to hear from you.

Cheers,
David

[1] http://wiki.github.com/aslakhellesoy/cucumber
[2] http://github.com/aslakhellesoy/cucumber/tree/master/features/



From ryan.briones at brionesandco.com  Fri Nov  6 17:27:40 2009
From: ryan.briones at brionesandco.com (Ryan Briones)
Date: Fri, 6 Nov 2009 17:27:40 -0500
Subject: [rspec-devel] describe "RSpec's documentation" do
In-Reply-To: <A3756A49-A10C-4138-8665-AAB730556A2B@gmail.com>
References: <A3756A49-A10C-4138-8665-AAB730556A2B@gmail.com>
Message-ID: <2566dc840911061427o53dc6294o5228045bf7cf8c5d@mail.gmail.com>

This sounds pretty cool. Are there any ideas or examples of how features
would get turned into end user documentation? My first thought is something
RDoc like would go in the free-form user story area... I'd certainly like to
help as time permitted. I'd definitely like to be more informed of rspec
internals.

On Fri, Nov 6, 2009 at 7:49 AM, David Chelimsky <dchelimsky at gmail.com>wrote:

> Hi all,
>
> describe "RSpec's documentation" do
>  it "should be helpful"
>  it "should be maintainable"
> end
>
> I've been wanting to improve RSpec's documentation situation for a long
> time, but my writing energies have been consumed by rspec itself and The
> RSpec Book for a longer time, and will continue to do so for the foreseeable
> future. So I'm going to need some help.
>
> The problem to solve is that we have (at least) four sources of
> documentation, each of which moves at its own pace and has evolved in its
> meaning/place:
>
> 1. The RSpec code examples that ship with RSpec
> 2. The Cucumber features that ship with RSpec
> 3. The github wiki: http://wiki.github.com/dchelimsky/rspec
> 4. http://rspec.info
>
> The model that Aslak and the Cucumber community has used has worked very
> well because it's a community effort, but there is still some duplication
> between what's on the wiki [1] and the Cucumber features/scenarios that ship
> with Cucumber [2].
>
> In the long run, what I'd like is the following:
>
> * Cucumber features that ship with RSpec become the authoritative end-user
> documentation. This is something that anybody can contribute to with
> patches, as it's all in files that ship with RSpec. I'd also like to use
> such an effort to push the envelope on Cucumber features as executable
> documentation. I think that with a little bit of work we could use the
> features to generate a website with meaningful organization/navigation. Is
> anybody already doing that?
> * RSpec code examples become a solid source of additional detailed
> documentation for those who want to either extend RSpec or debug problems.
> * http://rspec.info becomes a one pager like http://cukes.info
> * The github wiki becomes a community driven resource center with links to
> tutorials, blogs, matcher libraries, etc, etc
>
> I welcome suggestions, but I really need volunteers volunteers! I'm not
> going to be able to spend much personal time on this, so if there are any
> among you who are willing to coordinate with me and drive the effort, I'd
> love to hear from you.
>
> Cheers,
> David
>
> [1] http://wiki.github.com/aslakhellesoy/cucumber
> [2] http://github.com/aslakhellesoy/cucumber/tree/master/features/
>
>
> _______________________________________________
> rspec-devel mailing list
> rspec-devel at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-devel
>



-- 
Ryan Carmelo Briones
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-devel/attachments/20091106/a0bd423c/attachment.html>

From martin.emde at gmail.com  Sat Nov  7 01:43:42 2009
From: martin.emde at gmail.com (Martin Emde)
Date: Fri, 6 Nov 2009 22:43:42 -0800
Subject: [rspec-devel] should_yield (is it needed?)
Message-ID: <145359ad0911062243m66eff304oe3e3a007dd445cf0@mail.gmail.com>

I have the code working for this but I wanted an opinion on making a patch.

I sometimes have the need to expect that a method will yield a block it's
given. Usually this means something like this:

    yielded = false
    subject.method { yielded = true }
    yielded.should == true

which is a bit tedious and ugly. My solution might be just as ugly, but I
wanted to get feedback because it saves that tedious code.

    subject.method(&should_yield)

I wrote a few methods, that when called, return an object with #to_proc that
expects that the proc is called (or not called). I have the following forms
available fairly simply:

    subject.method(&should_not_yield)
    subject.method(&should_yield_with(object))

    # Expects 3 yields, one with each argument
    [1,2,3].each(&should_yield_each(1,2,3))

I think this is a little cleaner and the code is very simple. I wanted to
get an opinion on whether this is worth making into a patch.

Martin Emde
Tw: @martinemde
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-devel/attachments/20091106/e2b1c101/attachment.html>

From dchelimsky at gmail.com  Sat Nov  7 21:31:06 2009
From: dchelimsky at gmail.com (David Chelimsky)
Date: Sat, 7 Nov 2009 21:31:06 -0500
Subject: [rspec-devel] describe "RSpec's documentation" do
In-Reply-To: <2566dc840911061427o53dc6294o5228045bf7cf8c5d@mail.gmail.com>
References: <A3756A49-A10C-4138-8665-AAB730556A2B@gmail.com>
	<2566dc840911061427o53dc6294o5228045bf7cf8c5d@mail.gmail.com>
Message-ID: <57c63afe0911071831v1b24d575n4b7371fbd8ed1f31@mail.gmail.com>

On Fri, Nov 6, 2009 at 5:27 PM, Ryan Briones
<ryan.briones at brionesandco.com>wrote:

> This sounds pretty cool. Are there any ideas or examples of how features
> would get turned into end user documentation? My first thought is something
> RDoc like would go in the free-form user story area... I'd certainly like to
> help as time permitted. I'd definitely like to be more informed of rspec
> internals.
>

Yes, we should definitely beef up the narratives in each feature. Then we
need to generate the output as HTML and, the tricky part, generate some
wrapper HTML to make a site out of the different pages.

As for internals, my goal for the Cucumber features is to provide an
executable set of documentation for end users to understand how to use
RSpec. Not so much to expose internals, which I think is better addressed in
the RSpec code examples themselves. Make sense?


>
> On Fri, Nov 6, 2009 at 7:49 AM, David Chelimsky <dchelimsky at gmail.com>wrote:
>
>> Hi all,
>>
>> describe "RSpec's documentation" do
>>  it "should be helpful"
>>  it "should be maintainable"
>> end
>>
>> I've been wanting to improve RSpec's documentation situation for a long
>> time, but my writing energies have been consumed by rspec itself and The
>> RSpec Book for a longer time, and will continue to do so for the foreseeable
>> future. So I'm going to need some help.
>>
>> The problem to solve is that we have (at least) four sources of
>> documentation, each of which moves at its own pace and has evolved in its
>> meaning/place:
>>
>> 1. The RSpec code examples that ship with RSpec
>> 2. The Cucumber features that ship with RSpec
>> 3. The github wiki: http://wiki.github.com/dchelimsky/rspec
>> 4. http://rspec.info
>>
>> The model that Aslak and the Cucumber community has used has worked very
>> well because it's a community effort, but there is still some duplication
>> between what's on the wiki [1] and the Cucumber features/scenarios that ship
>> with Cucumber [2].
>>
>> In the long run, what I'd like is the following:
>>
>> * Cucumber features that ship with RSpec become the authoritative end-user
>> documentation. This is something that anybody can contribute to with
>> patches, as it's all in files that ship with RSpec. I'd also like to use
>> such an effort to push the envelope on Cucumber features as executable
>> documentation. I think that with a little bit of work we could use the
>> features to generate a website with meaningful organization/navigation. Is
>> anybody already doing that?
>> * RSpec code examples become a solid source of additional detailed
>> documentation for those who want to either extend RSpec or debug problems.
>> * http://rspec.info becomes a one pager like http://cukes.info
>> * The github wiki becomes a community driven resource center with links to
>> tutorials, blogs, matcher libraries, etc, etc
>>
>> I welcome suggestions, but I really need volunteers volunteers! I'm not
>> going to be able to spend much personal time on this, so if there are any
>> among you who are willing to coordinate with me and drive the effort, I'd
>> love to hear from you.
>>
>> Cheers,
>> David
>>
>> [1] http://wiki.github.com/aslakhellesoy/cucumber
>> [2] http://github.com/aslakhellesoy/cucumber/tree/master/features/
>>
>>
>> _______________________________________________
>> rspec-devel mailing list
>> rspec-devel at rubyforge.org
>> http://rubyforge.org/mailman/listinfo/rspec-devel
>>
>
>
>
> --
> Ryan Carmelo Briones
>
> _______________________________________________
> rspec-devel mailing list
> rspec-devel at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-devel/attachments/20091107/c3a0e477/attachment.html>

From ryan.briones at brionesandco.com  Sun Nov  8 11:49:39 2009
From: ryan.briones at brionesandco.com (Ryan Briones)
Date: Sun, 8 Nov 2009 11:49:39 -0500
Subject: [rspec-devel] describe "RSpec's documentation" do
In-Reply-To: <57c63afe0911071831v1b24d575n4b7371fbd8ed1f31@mail.gmail.com>
References: <A3756A49-A10C-4138-8665-AAB730556A2B@gmail.com>
	<2566dc840911061427o53dc6294o5228045bf7cf8c5d@mail.gmail.com>
	<57c63afe0911071831v1b24d575n4b7371fbd8ed1f31@mail.gmail.com>
Message-ID: <2566dc840911080849r13af0fe6h7bc1343f52d4e1c2@mail.gmail.com>

On Sat, Nov 7, 2009 at 9:31 PM, David Chelimsky <dchelimsky at gmail.com>wrote:

> On Fri, Nov 6, 2009 at 5:27 PM, Ryan Briones <
> ryan.briones at brionesandco.com> wrote:
>
>> This sounds pretty cool. Are there any ideas or examples of how features
>> would get turned into end user documentation? My first thought is something
>> RDoc like would go in the free-form user story area... I'd certainly like to
>> help as time permitted. I'd definitely like to be more informed of rspec
>> internals.
>>
>
> Yes, we should definitely beef up the narratives in each feature. Then we
> need to generate the output as HTML and, the tricky part, generate some
> wrapper HTML to make a site out of the different pages.
>
> As for internals, my goal for the Cucumber features is to provide an
> executable set of documentation for end users to understand how to use
> RSpec. Not so much to expose internals, which I think is better addressed in
> the RSpec code examples themselves. Make sense?
>

Yes. Being more familiar with the internals was more for my own edification.
;)


>
>
>>
>> On Fri, Nov 6, 2009 at 7:49 AM, David Chelimsky <dchelimsky at gmail.com>wrote:
>>
>>> Hi all,
>>>
>>> describe "RSpec's documentation" do
>>>  it "should be helpful"
>>>  it "should be maintainable"
>>> end
>>>
>>> I've been wanting to improve RSpec's documentation situation for a long
>>> time, but my writing energies have been consumed by rspec itself and The
>>> RSpec Book for a longer time, and will continue to do so for the foreseeable
>>> future. So I'm going to need some help.
>>>
>>> The problem to solve is that we have (at least) four sources of
>>> documentation, each of which moves at its own pace and has evolved in its
>>> meaning/place:
>>>
>>> 1. The RSpec code examples that ship with RSpec
>>> 2. The Cucumber features that ship with RSpec
>>> 3. The github wiki: http://wiki.github.com/dchelimsky/rspec
>>> 4. http://rspec.info
>>>
>>> The model that Aslak and the Cucumber community has used has worked very
>>> well because it's a community effort, but there is still some duplication
>>> between what's on the wiki [1] and the Cucumber features/scenarios that ship
>>> with Cucumber [2].
>>>
>>> In the long run, what I'd like is the following:
>>>
>>> * Cucumber features that ship with RSpec become the authoritative
>>> end-user documentation. This is something that anybody can contribute to
>>> with patches, as it's all in files that ship with RSpec. I'd also like to
>>> use such an effort to push the envelope on Cucumber features as executable
>>> documentation. I think that with a little bit of work we could use the
>>> features to generate a website with meaningful organization/navigation. Is
>>> anybody already doing that?
>>> * RSpec code examples become a solid source of additional detailed
>>> documentation for those who want to either extend RSpec or debug problems.
>>> * http://rspec.info becomes a one pager like http://cukes.info
>>> * The github wiki becomes a community driven resource center with links
>>> to tutorials, blogs, matcher libraries, etc, etc
>>>
>>> I welcome suggestions, but I really need volunteers volunteers! I'm not
>>> going to be able to spend much personal time on this, so if there are any
>>> among you who are willing to coordinate with me and drive the effort, I'd
>>> love to hear from you.
>>>
>>> Cheers,
>>> David
>>>
>>> [1] http://wiki.github.com/aslakhellesoy/cucumber
>>> [2] http://github.com/aslakhellesoy/cucumber/tree/master/features/
>>>
>>>
>>> _______________________________________________
>>> rspec-devel mailing list
>>> rspec-devel at rubyforge.org
>>> http://rubyforge.org/mailman/listinfo/rspec-devel
>>>
>>
>>
>>
>> --
>> Ryan Carmelo Briones
>>
>> _______________________________________________
>> rspec-devel mailing list
>> rspec-devel at rubyforge.org
>> http://rubyforge.org/mailman/listinfo/rspec-devel
>>
>
>
> _______________________________________________
> rspec-devel mailing list
> rspec-devel at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-devel
>



-- 
Ryan Carmelo Briones
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-devel/attachments/20091108/f134dce4/attachment-0001.html>

From peter.a.jaros at gmail.com  Tue Nov 10 00:34:55 2009
From: peter.a.jaros at gmail.com (Peter Jaros)
Date: Mon, 9 Nov 2009 21:34:55 -0800
Subject: [rspec-devel] should_yield (is it needed?)
In-Reply-To: <145359ad0911062243m66eff304oe3e3a007dd445cf0@mail.gmail.com>
References: <145359ad0911062243m66eff304oe3e3a007dd445cf0@mail.gmail.com>
Message-ID: <937d9d810911092134i58e8587cx764c65ecea59077e@mail.gmail.com>

I happen to think that's brilliant.

Peter


On Fri, Nov 6, 2009 at 10:43 PM, Martin Emde <martin.emde at gmail.com> wrote:
> I have the code working for this but I wanted an opinion on making a patch.
> I sometimes have the need to expect that a method will yield a block it's
> given. Usually this means something like this:
> ?? ?yielded = false
> ?? ?subject.method { yielded = true }
> ?? ?yielded.should == true
> which is a bit tedious and ugly. My solution might be just as ugly, but I
> wanted to get feedback because it saves that tedious code.
> ?? ?subject.method(&should_yield)
> I wrote a few methods, that when called, return an object with #to_proc that
> expects that the proc is called (or not called). I have the following forms
> available fairly simply:
> ?? ?subject.method(&should_not_yield)
> ?? ?subject.method(&should_yield_with(object))
> ?? ?# Expects 3 yields, one with each argument
> ?? ?[1,2,3].each(&should_yield_each(1,2,3))
>
> I think this is a little cleaner and the code is very simple. I wanted to
> get an opinion on whether this is worth making into a patch.
> Martin Emde
> Tw: @martinemde
>
> _______________________________________________
> rspec-devel mailing list
> rspec-devel at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-devel
>

From dchelimsky at gmail.com  Tue Nov 10 20:00:22 2009
From: dchelimsky at gmail.com (David Chelimsky)
Date: Tue, 10 Nov 2009 17:00:22 -0800
Subject: [rspec-devel] should_yield (is it needed?)
In-Reply-To: <145359ad0911062243m66eff304oe3e3a007dd445cf0@mail.gmail.com>
References: <145359ad0911062243m66eff304oe3e3a007dd445cf0@mail.gmail.com>
Message-ID: <57c63afe0911101700q673c5833l51ce74598381f90f@mail.gmail.com>

On Fri, Nov 6, 2009 at 10:43 PM, Martin Emde <martin.emde at gmail.com> wrote:

> I have the code working for this but I wanted an opinion on making a patch.
>
> I sometimes have the need to expect that a method will yield a block it's
> given. Usually this means something like this:
>
>     yielded = false
>     subject.method { yielded = true }
>     yielded.should == true
>
> which is a bit tedious and ugly. My solution might be just as ugly, but I
> wanted to get feedback because it saves that tedious code.
>
>     subject.method(&should_yield)
>
> I wrote a few methods, that when called, return an object with #to_proc
> that expects that the proc is called (or not called). I have the following
> forms available fairly simply:
>
>     subject.method(&should_not_yield)
>     subject.method(&should_yield_with(object))
>
>     # Expects 3 yields, one with each argument
>     [1,2,3].each(&should_yield_each(1,2,3))
>
> I think this is a little cleaner and the code is very simple. I wanted to
> get an opinion on whether this is worth making into a patch.
>
> Martin Emde
> Tw: @martinemde


Generally this looks really nice, and I can see the use, but it's so
different from everything else that I need to think about it a bit more.
Have you played around w/ any other syntax options that would be more
aligned w/ the "actual.should matcher" format? Something like:

[1,2,3].should yield_on(:each) ???

>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-devel/attachments/20091110/452f2fbb/attachment.html>

From martin.emde at gmail.com  Sun Nov 29 15:11:16 2009
From: martin.emde at gmail.com (Martin Emde)
Date: Sun, 29 Nov 2009 12:11:16 -0800
Subject: [rspec-devel] should_yield (is it needed?)
In-Reply-To: <57c63afe0911101700q673c5833l51ce74598381f90f@mail.gmail.com>
References: <145359ad0911062243m66eff304oe3e3a007dd445cf0@mail.gmail.com> 
	<57c63afe0911101700q673c5833l51ce74598381f90f@mail.gmail.com>
Message-ID: <145359ad0911291211u29b8f374k3319aa86f43eaf9a@mail.gmail.com>

On Tue, Nov 10, 2009 at 5:00 PM, David Chelimsky <dchelimsky at gmail.com>wrote:

>
> [1,2,3].should yield_on(:each) ???
>

This does follow rspec syntax more closely... Let's run through a few use
cases I can imagine.

current_user.stub!(:admin?).and_return(true)
helper.should yield_on(:admin_only)
# helper.admin_only &should_yield

[1,2,3].should yield_on(:each).each_of(1,2,3)
# [1,2,3].each &should_yield_each(1,2,3)

h = { :a => 1, :b => 2 }
h.should yield_on(:each).each_of(*h.to_a)
h.each &should_yield_each(*h.to_a)

helper.should yield_on(:link_to_function, "link
text").with(an_instance_of(JavaScriptHelper::JavaScriptBuilder))
#  helper.link_to_function "link text",
&should_yield_with(an_instance_of(JavaScriptHelper::JavaScriptBuilder))

I think both are pretty clear until the last example when this part in my
format:  *"link text", &should_yield(...)*   starts to confuse what's going
on exactly. It very clearly breaks from rspec syntax in that example.

helper.link_to_functio("link text", &assert_yielded_block)

That actually makes a bit more sense since the intention is clear. I'm
passing a block that asserts that it will be yielded. However, this isn't
rspec at all written like that.

The yield_on format seems to specify "When I call this method on the
receiver, I expect it to yield." This is very similar to user.should
be_an_admin in that the actual method call is not being called on the
receiver but passed into the matcher.

Is this something we'd like to add to rspec? If so, I'll work out a patch.

Martin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-devel/attachments/20091129/aeec471c/attachment.html>