I'd love to see a documentation system similar to what python has, and YARD comes pretty close. Since we haven't been able to get any sort of annotation system into Ruby, a smart, standard doc format plus an API to process it seems like the next best thing. Yehuda Katz wrote: > One project that has been in the works for a while and shows a lot of > promise is YARD. The maintainer got sick a while back but has now > returned and is proceeding full-steam-ahead. > > YARD supports structured docs (@param foo<String>) but also allows for > rdoc-style completely unstructured docs if that's your piece of cake. > Personally, I find that I prefer rdoc style in application and > structured style in languages, libraries, and frameworks. > > YARD has its own parser, so it would be a worthy replacement for rdoc. > > -- Yehuda > > 2009/2/1 Luiz Vitor Martinez Cardoso <grabber / gmail.com > <mailto:grabber / gmail.com>> > > People, > > Look for that: http://docs.python.org/download.html, try to search > some functions/methods in "Quick Search" field (example: bisect, > urllib, re...). The search field is missing at ruby, and it's make > the job easier. > > The layout of the doc core system is another point. We need to > improve the interface, show minus things and be more expressive. > > Note that I'm nothing suggesting solutions, just putting the > problems on the table. If the community shows this demand I'll happy > to help improve it! > > > Regards, > Luiz Vitor. > > > On Sun, Feb 1, 2009 at 2:42 PM, <znmeb / cesmail.net > <mailto:znmeb / cesmail.net>> wrote: > > Quoting Austin Ziegler <halostatue / gmail.com > <mailto:halostatue / gmail.com>>: > > On Sun, Feb 1, 2009 at 10:51 AM, Luiz Vitor Martinez Cardoso > <grabber / gmail.com <mailto:grabber / gmail.com>> wrote: > > What the Ruby community think about developing a better > documentation > system. Something like Python Documentation? > > > I'm not familiar with "Python Documentation". What exactly > do you mean > by "documentation system" (that is, what do you feel that Ruby > currently offers), and what do you mean by "better" (that > is, what do > you feel that Ruby currently lacks). > > -austin > -- > Austin Ziegler * halostatue / gmail.com > <mailto:halostatue / gmail.com> * http://www.halostatue.ca/ > * austin / halostatue.ca > <mailto:austin / halostatue.ca> * http://www.halostatue.ca/feed/ > * austin / zieglers.ca <mailto:austin / zieglers.ca> > > > > I'm not familiar with Python documentation either. And I know > we've had this discussion before, but I'm a big fan of "literate > programming" and "reproducible research." > > As a "community member", though, I'd expect changes to the > "documentation system" to be created the same way everything > else here is created -- by patches, discussions on mailing lists > and in IRC, test-driven and behavior-driven development, etc. So > if the original poster has some ideas, I'd certainly like to see > what they are, and how they compare with RDoc / RI. Anybody can > start a project on RubyForge or Github, and some projects are > appealing enough that developers will gravitate to them. > > When I run out of other interesting projects, I might revisit > the whole "literate programming in Ruby" concept. But the thing > is -- what I want to do already exists in the R language because > some R community members built it. So there's little incentive > for me to actually create something. :) > > > -- > M. Edward (Ed) Borasky > > I've never met a happy clam. In fact, most of them were pretty > steamed. > > > > > -- > Regards, > > Luiz Vitor Martinez Cardoso > cel.: (11) 8187-8662 > blog: rubz.org <http://rubz.org> > engineer student at maua.br <http://maua.br> > > "Posso nunca chegar a ser o melhor engenheiro do mundo, mas tenha > certeza de que eu vou lutar com todas as minhas forças para ser o > melhor engenheiro que eu puder ser" > > > > > -- > Yehuda Katz > Developer | Engine Yard > (ph) 718.877.1325