Hi,
I would love to hear your opinion on the idea of “combining RDoc and RSpec to create testable documentation”. Let me explain:
Given you have several RDoc files like this one:
= Examples
Some example code snippets.
== Authentication
Supported authentication methods:
* HTTP basic authentication
Example:
Net::HTTP.start('www.example.com') do |http|
req = Net::HTTP::Get.new('/secret-page.html')
req.basic_auth 'account', 'password'
response = http.request(req)
end
-
These RDoc files are parsed and code-blocks followed by a certain keyword (like “Example:” are saved for step 3.
-
An HTML documentation based on the RDoc files is generated, just like you would create an RDoc task via Rake::RDocTask and run “rake rdoc”. Nothing special here.
-
The code-blocks extracted from the RDoc files will be made accessable to some RSpec tests and run to verify they actually work.
I know this might be a lot of work, but it would allow you to create a fairly decent documentation along with examples of code that actually work.
Also I don’t know if it’s the best idea, but it’s certainly worth starting a discussion. Separating code from documentation (and keeping the documentation up to date) is pretty difficult, so by combining both life might be a little easier.
I appreciate any comments, ideas and feedback. I’m not aware of approach to combine documentation and tested examples, so please let me know if I’m missing something.
When I worked at Chargify (and I believe they still do this) we wrote Cucumber tests for our API, then published the tests because they made good documentation.
http://support.chargify.com/faqs/api/api-coupons
I'd rather write RSpecs and Cucumber tests that generate documentation than write documentation that also tested the code. So, instead of RDoc => RSpec I prefer RSpec => RDoc. This would also have the benefit of being able to mark certain tests as "nodoc" so you don't get the edge-case bloat constellationsoft was talking about.