From: Charles Oliver Nutter Date: 2009-02-02T14:58:31+09:00 Subject: [ruby-core:21731] Re: New documentation system! 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) 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 > > > 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, > wrote: > > Quoting Austin Ziegler >: > > On Sun, Feb 1, 2009 at 10:51 AM, Luiz Vitor Martinez Cardoso > > 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 > * http://www.halostatue.ca/ > * austin@halostatue.ca > * http://www.halostatue.ca/feed/ > * 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 > engineer student at 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