Sorry to have to post this again - it was probably under the wrong subject and went unnoticed. Is there a standard for providing user documentation for methods that I expose through we services? The default documentation (method names and return types) that appears when the user visits http://localhost:3000/backend/invoke is concise and correct, but a bit terse. How can I give my users a little more? Maybe even include an example for them on the same page. Do I manually insert this in the rendered view? Or is there, like most things Ruby that I am discovering, a much more elegant way of doing this using RDoc? Bealach
You''re probably looking for WSDL ... anyway if it''s web services you''re looking at then it''s probably developer documentation, end-users shouldn''t be touching this at all. The WSDL in ActionWebService is in http://localhost:3000/<your controller>/service.wsdl by default but u can change it at routes.rb, but if u''re not sure what WSDL is abt, u should look it up a bit first in Google. Bealach Na Bo wrote:> Sorry to have to post this again - it was probably under the wrong > subject and went unnoticed. > > Is there a standard for providing user documentation for methods that > I expose through we services? > > The default documentation (method names and return types) that > appears when the user visits http://localhost:3000/backend/invoke is > concise and correct, but a bit terse. How can I give my users a little > more? Maybe even include an example for them on the same page. Do I > manually insert this in the rendered view? Or is there, like most > things Ruby that I am discovering, a much more elegant way of doing > this using RDoc? > > Bealach > _______________________________________________ > Rails mailing list > Rails@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails > >-- Sau Sheong http://blog.saush.com http://read.saush.com http://jaccal.sourceforge.net
Thanks for your comments Sau. My "end users" are developers. The work in things like Visual Studio and Perl environments. I''m trying to provide a "black box" service, exposing only the methods (and documentation for these methods) that they need to talk SOAP/XMLrpc with my black box that talks to DB back ends. Basically I want a simple way of integrating the documentation for the methods that I expose through the web services api into something like the page that RoR generated for testing the exposed methods. The WSDL is a little deeper down in the system. The users are already able to choose a protocol, such as SOAP and use CPAN libraries for Perl to talk SOAP with my DB back end through my web services api. Regards, Bealach On 4/22/06, Chang Sau Sheong <cssheong@pacific.net.sg> wrote:> You''re probably looking for WSDL ... anyway if it''s web services you''re > looking at then it''s probably developer documentation, end-users > shouldn''t be touching this at all. The WSDL in ActionWebService is in > http://localhost:3000/<your controller>/service.wsdl by default but u > can change it at routes.rb, but if u''re not sure what WSDL is abt, u > should look it up a bit first in Google. > > Bealach Na Bo wrote: > > Sorry to have to post this again - it was probably under the wrong > > subject and went unnoticed. > > > > Is there a standard for providing user documentation for methods that > > I expose through we services? > > > > The default documentation (method names and return types) that > > appears when the user visits http://localhost:3000/backend/invoke is > > concise and correct, but a bit terse. How can I give my users a little > > more? Maybe even include an example for them on the same page. Do I > > manually insert this in the rendered view? Or is there, like most > > things Ruby that I am discovering, a much more elegant way of doing > > this using RDoc? > > > > Bealach > > _______________________________________________ > > Rails mailing list > > Rails@lists.rubyonrails.org > > http://lists.rubyonrails.org/mailman/listinfo/rails > > > > > > > -- > Sau Sheong > > http://blog.saush.com > http://read.saush.com > http://jaccal.sourceforge.net > > _______________________________________________ > Rails mailing list > Rails@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails >
On Apr 21, 2006, at 1:09 AM, Bealach Na Bo wrote:> The default documentation (method names and return types) that > appears when the user visits http://localhost:3000/backend/invoke is > concise and correct, but a bit terse. How can I give my users a little > more? Maybe even include an example for them on the same page. Do I > manually insert this in the rendered view? Or is there, like most > things Ruby that I am discovering, a much more elegant way of doing > this using RDoc?My plan, when this becomes important for our service, is to use some mixture of RDoc and/or Textile to generate the docs from source. Semi-literate programming is my friend. -- ~akk http://therealadam.com