Document config options #723

Merged
merged 10 commits into from Jan 1, 2013

Conversation

Projects
None yet
5 participants
@charlietanksley
Contributor

charlietanksley commented Nov 7, 2012

This pull request isn't yet complete. There are still a handful of options in rspec-core to document like this, and then I need to document the ones in rspec-rails. This pull request is actually the first part of trying to close rspec/rspec-rails#422.

I'm submitting this early just to make sure I'm on the right track with my approach. Let me know if I need to do anything differently, and I'll let you know when the pull request is complete! 馃樃

@soulcutter

This comment has been minimized.

Show comment Hide comment
@soulcutter

soulcutter Nov 11, 2012

Member

These look great to me. Awesome work 馃憤

Member

soulcutter commented Nov 11, 2012

These look great to me. Awesome work 馃憤

@alindeman

This comment has been minimized.

Show comment Hide comment
@alindeman

alindeman Nov 13, 2012

Contributor

I skimmed over these, and it's all positive. @charlietanksley, should I review more in depth and merge these if everything is OK?

Contributor

alindeman commented Nov 13, 2012

I skimmed over these, and it's all positive. @charlietanksley, should I review more in depth and merge these if everything is OK?

@charlietanksley

This comment has been minimized.

Show comment Hide comment
@charlietanksley

charlietanksley Nov 13, 2012

Contributor

@alinderman not yet. I'd like to document the remaining options. I just wanted to make sure I was on the right track before finishing. I'll get to that this week and let you know when it is done. Thanks.

@soulcutter thanks!

Contributor

charlietanksley commented Nov 13, 2012

@alinderman not yet. I'd like to document the remaining options. I just wanted to make sure I was on the right track before finishing. I'll get to that this week and let you know when it is done. Thanks.

@soulcutter thanks!

@charlietanksley

This comment has been minimized.

Show comment Hide comment
@charlietanksley

charlietanksley Nov 13, 2012

Contributor

Sorry, for the typo in your name, @alindeman!

Contributor

charlietanksley commented Nov 13, 2012

Sorry, for the typo in your name, @alindeman!

charlietanksley added some commits Nov 4, 2012

link to documentation for order and seed options
Since `order` and `seed` are pretty tightly coupled, it seems like
these should be documented together. But the only way I can think of
to write a feature for seed would be to try and run a spec, capture
the seed, then insert that into a config block. But that seems way too
complicated to be informative as documentation. So after consulting
with @alindeman I opted to just link to where these features are
documented for the command line options.
@charlietanksley

This comment has been minimized.

Show comment Hide comment
@charlietanksley

charlietanksley Dec 7, 2012

Contributor

The only part of rspec/rspec-rails#422 left to do is put a link to the Rdoc on https://www.relishapp.com/rspec. I couldn't find that home page so I didn't know how to add that, but I'm happy to add it if you'll point me in the right direction.

And let me know if there are any parts of any of these that need to be changed for any reason. Or if I should squash them to one big commit. 馃槃

Contributor

charlietanksley commented Dec 7, 2012

The only part of rspec/rspec-rails#422 left to do is put a link to the Rdoc on https://www.relishapp.com/rspec. I couldn't find that home page so I didn't know how to add that, but I'm happy to add it if you'll point me in the right direction.

And let me know if there are any parts of any of these that need to be changed for any reason. Or if I should squash them to one big commit. 馃槃

@dchelimsky

This comment has been minimized.

Show comment Hide comment
@dchelimsky

dchelimsky Dec 7, 2012

Member

RDoc is on http://rubydoc.info (http://relishapp.com supports Cucumber features). These docs will show up automatically once this is merged under http://rubydoc.info/github/rspec/rspec-core and then under http://rubydoc.info/gems/rspec-core when we do a release.

Member

dchelimsky commented Dec 7, 2012

RDoc is on http://rubydoc.info (http://relishapp.com supports Cucumber features). These docs will show up automatically once this is merged under http://rubydoc.info/github/rspec/rspec-core and then under http://rubydoc.info/gems/rspec-core when we do a release.

@charlietanksley

This comment has been minimized.

Show comment Hide comment
@charlietanksley

charlietanksley Dec 7, 2012

Contributor

Awesome. I thought in the issue over on rspec/rails one of the suggestions was to put a link to rdoc from relishapp. Sounds like that is unnecessary, though. :)

Contributor

charlietanksley commented Dec 7, 2012

Awesome. I thought in the issue over on rspec/rails one of the suggestions was to put a link to rdoc from relishapp. Sounds like that is unnecessary, though. :)

@alindeman

This comment has been minimized.

Show comment Hide comment
@alindeman

alindeman Dec 11, 2012

Contributor

@charlietanksley, is this ready to go? We're discussing what #error_stream does, but for now I think it's fine to ignore it.

Contributor

alindeman commented Dec 11, 2012

@charlietanksley, is this ready to go? We're discussing what #error_stream does, but for now I think it's fine to ignore it.

@charlietanksley

This comment has been minimized.

Show comment Hide comment
@charlietanksley

charlietanksley Dec 11, 2012

Contributor

@alindeman, yes, it's good to go, then.

Contributor

charlietanksley commented Dec 11, 2012

@alindeman, yes, it's good to go, then.

+ end
+ """
+ When I run `rspec spec/example_spec.rb`
+ Then the examples should all pass

This comment has been minimized.

Show comment Hide comment
@myronmarston

myronmarston Dec 11, 2012

Member

I'm glad we're getting some docs in place for the DRb stuff, but I'm not sure that these scenarios have much documentation value...they don't demonstrate what the DRb options do; they just show that when you set them, the configuration object stores the values you set.

This is going to sound funny given that I'm the lead maintainer for rspec now...but I'm not even sure how to use the DRb options (I've never used the options). I know spork uses it but it'd be nice to document how to use it w/o spork. Not sure how feasible it is to demonstrate that with a scenario here, but if it was feasible, it would be a huge improvement, I think. Or, even if it's not feasible, maybe some additional text at the top explaining why you would want to use the options and how you would use it?

@myronmarston

myronmarston Dec 11, 2012

Member

I'm glad we're getting some docs in place for the DRb stuff, but I'm not sure that these scenarios have much documentation value...they don't demonstrate what the DRb options do; they just show that when you set them, the configuration object stores the values you set.

This is going to sound funny given that I'm the lead maintainer for rspec now...but I'm not even sure how to use the DRb options (I've never used the options). I know spork uses it but it'd be nice to document how to use it w/o spork. Not sure how feasible it is to demonstrate that with a scenario here, but if it was feasible, it would be a huge improvement, I think. Or, even if it's not feasible, maybe some additional text at the top explaining why you would want to use the options and how you would use it?

This comment has been minimized.

Show comment Hide comment
@alindeman

alindeman Dec 12, 2012

Contributor

I know spork uses it but it'd be nice to document how to use it w/o spork.

Is there a common use case outside of tools like spork? I also am not too familiar with them beyond that, if so.

@alindeman

alindeman Dec 12, 2012

Contributor

I know spork uses it but it'd be nice to document how to use it w/o spork.

Is there a common use case outside of tools like spork? I also am not too familiar with them beyond that, if so.

This comment has been minimized.

Show comment Hide comment
@charlietanksley

charlietanksley Dec 15, 2012

Contributor

I agree that this doesn't provide tons of documentation value. @myronmarston, you're right that it merely shows that the DRb option can be turned on and that you can set the port (and that there is no port set by default).

I haven't the foggiest clue how to document this any further. If you guys don't know how it is used, I sure don't! So I'd vote that if you think that this documentation adds nothing, we just scrap it. I think the other documentation here is helpful, so I'd like to see it added even if we drop the DRb documentation. Do feel free to cut these features. Whatever you see fit to do.

@charlietanksley

charlietanksley Dec 15, 2012

Contributor

I agree that this doesn't provide tons of documentation value. @myronmarston, you're right that it merely shows that the DRb option can be turned on and that you can set the port (and that there is no port set by default).

I haven't the foggiest clue how to document this any further. If you guys don't know how it is used, I sure don't! So I'd vote that if you think that this documentation adds nothing, we just scrap it. I think the other documentation here is helpful, so I'd like to see it added even if we drop the DRb documentation. Do feel free to cut these features. Whatever you see fit to do.

This comment has been minimized.

Show comment Hide comment
@myronmarston

myronmarston Dec 15, 2012

Member

We'll definitely merge the rest of the documentation stuff you wrote up (it's really great) but I'm hoping @dchelimsky can weigh in on the DRb options first. @dchelimsky -- if you get the chance, it'd be nice to get a description of how to use these options, if for no other reason than to provide a "here's how to use them guide" for me so if/when I refactor any code involving the DRb stuff I can verify I haven't broken it. If it's feasible to turn that into a cuke we can do that as well.

@myronmarston

myronmarston Dec 15, 2012

Member

We'll definitely merge the rest of the documentation stuff you wrote up (it's really great) but I'm hoping @dchelimsky can weigh in on the DRb options first. @dchelimsky -- if you get the chance, it'd be nice to get a description of how to use these options, if for no other reason than to provide a "here's how to use them guide" for me so if/when I refactor any code involving the DRb stuff I can verify I haven't broken it. If it's feasible to turn that into a cuke we can do that as well.

This comment has been minimized.

Show comment Hide comment
@charlietanksley

charlietanksley Dec 15, 2012

Contributor

Cool. If I know how to document the DRb options I'm happy to do it. I'll watch for updates :)

@charlietanksley

charlietanksley Dec 15, 2012

Contributor

Cool. If I know how to document the DRb options I'm happy to do it. I'll watch for updates :)

This comment has been minimized.

Show comment Hide comment
@dchelimsky

dchelimsky Dec 16, 2012

Member

Basically, you add --drbto the command line to run via spork. That's it. AKAIK, drb is only ever used w/ spork and drb_port is never used (well, it's used internally, but never by a user).

@dchelimsky

dchelimsky Dec 16, 2012

Member

Basically, you add --drbto the command line to run via spork. That's it. AKAIK, drb is only ever used w/ spork and drb_port is never used (well, it's used internally, but never by a user).

This comment has been minimized.

Show comment Hide comment
@myronmarston

myronmarston Dec 16, 2012

Member

I knew spork was the primary library that relies on rspec's DRb support. Spork's usage of this should be relying upon public APIs that another bit of code or library could use as well, though, right? Can we document how the rspec DRb protocol works (as a standalone thing, without referencing spork as the only way to use it?). I'm thinking something along the lines of "start rspec with the drb option, then send it commands by doing XYZ".

Maybe it's not possible to distill how spork uses rspec down into something easily documentable, but it would be nice to do so.

@myronmarston

myronmarston Dec 16, 2012

Member

I knew spork was the primary library that relies on rspec's DRb support. Spork's usage of this should be relying upon public APIs that another bit of code or library could use as well, though, right? Can we document how the rspec DRb protocol works (as a standalone thing, without referencing spork as the only way to use it?). I'm thinking something along the lines of "start rspec with the drb option, then send it commands by doing XYZ".

Maybe it's not possible to distill how spork uses rspec down into something easily documentable, but it would be nice to do so.

@alindeman alindeman referenced this pull request in rspec/rspec-rails Dec 12, 2012

Closed

RSpec.configure doc? #422

@myronmarston myronmarston merged commit 4385437 into rspec:master Jan 1, 2013

1 check failed

default The Travis build failed
Details
@myronmarston

This comment has been minimized.

Show comment Hide comment
@myronmarston

myronmarston Jan 1, 2013

Member

@charlietanksley Thanks for your hard work on this, and sorry for taking so long to merge this! I just merged it finally.

Member

myronmarston commented Jan 1, 2013

@charlietanksley Thanks for your hard work on this, and sorry for taking so long to merge this! I just merged it finally.

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