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.