First of all let me congratulate all the team involved on the
creation of Rails 2! What an excellent advancement on an advanced
framework!
I have a question about the “new” RESTful resources. Imagine I use
extensively this new approach on a new website. What is the best way
to inform my users about the RESTful resources? Is there some kind of
automatic generation of documentation? Or am I missing the big
picture completely?
What would you need to inform them about? Most of the major changes are
in
the back end and the only “serious” change I can think off the top of my
head is the changing of semi-colon to forward-slash for the action
specification on member objects of a Restful resource.
automatic generation of documentation? Or am I missing the big
Tel: +351 21 330 42 20
Fax: +351 21 330 42 19
Calçada Marquês de Abrantes, 45 - 3º Dto
1200-718 Lisboa
I believe he wants to generate documentation about his available
RESTful API.
And actually that would be a cool tool.
Brain starts moving…
–Jeremy
Yes that was exactly what I was thinking! I want to tell the users:
“hey! I have a beautiful API! How do you use it? Here is the
documentation: …”.
I don’t really know if this is somewhat possible, but at least a
skeleton documentation seems feasible. I could then fill the
description about each method. Or it could be copied from the
existing application documentation
it’s nearing 10pm here, been up since 7 and I’ve been coding most of the
day, but maybe rake doc:app would do the skeleton your after? The
content is
specified by putting comments above the methods, like this:
#This method will destroy the world
def nuke_it_all
…
end
Yeah, you could do that, but you’d have to :nodoc: all the stuff you
didn’t want.
It’d be cool to have an RDoc hooked tool that you could say something
like:
resdoc accounts sessions pages
…and then it would crawl into your controllers directory, grab the
documentation for it, and then spit out a nice looking REST API doc
(which would likely look different than an RDoc). In RDoc, all the
methods would look like create, update, etc for every controller,
making them indistinguishable. If a person wanted to learn about the
resources, they’d have to dig into your classes, and if they do that,
they’re looking at the docs for your app not the exposed API.
