On Mon, F= eb 2, 2009 at 3:58 AM, Charles Oliver Nutter <charles.nutter@sun.com> wr= ote:

I'd love to s= ee 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 li= ke the next best thing.

Yehuda Katz wrote:

One project that has been in the works for a while and shows a lot of promi= se is YARD. The maintainer got sick a while back but has now returned and i= s proceeding full-steam-ahead.

YARD supports structured docs (@param foo<String>) but also allows fo= r 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 searc= h
some functions/methods in "Quick Search" field (exa= mple: bisect,
urllib, re...). The search field is missing at ruby, and it&#= 39;s make
the job easier.

The layout of the doc core system is another point. We need t= o
improve the interface, show minus things and be more expressi= ve.

Note that I'm nothing suggesting solutions, just putting = the
problems on the table. If the community shows this demand I&#= 39;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 commu= nity think about developing a better
documentation
system. Something l= ike Python Documentation?

I'm not familiar with "P= ython Documentation". What exactly
do you mean
by "documentation system&quo= t; (that is, what do you feel that Ruby
currently offers), and what do yo= u mean by "better" (that
is, what do
you feel that Ruby currently lack= s).

-austin
--
Austin Ziegler * halostatue@gmail.com
<mailto:halostatue@gmail.com> * http://www.halostatue.ca/<= /a>
&nbs= p; * austin@halostatue.ca
<mailto:austin@halostatue.ca> * http://www.halostatue= .ca/feed/
&nbs= p; * a= ustin@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 resear= ch."

As a "community member", though, I= 9;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 dev= elopment, 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 som= e 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&qu= ot; 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) B= orasky

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<= /a> <http://rubz.org&g= t;
engineer student at maua.br <http://mau= a.br>

"Posso nunca chegar a ser o melhor engenheiro do mundo, = mas tenha
certeza de que eu vou lutar com todas as minhas for=E7as para= ser o
melhor engenheiro que eu puder ser"

--
Yehuda Katz
Developer | Engine Yard
(ph) 718.877.1325