[ruby-core:21719] Re: New documentation system!

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 <[e-mail]>

> 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 th=
e
> 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, <[e-mail]> wrote:
>
>> Quoting Austin Ziegler <[e-mail]>:
>>
>>  On Sun, Feb 1, 2009 at 10:51 AM, Luiz Vitor Martinez Cardoso
>>> <[e-mail]> 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 * [e-mail] * http://www.halostatue.ca/
>>>               * [e-mail] * http://www.halostatue.ca/feed/
>>>               * [e-mail]
>>>
>>>
>>>
>> 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 "documentatio=
n
>> 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 ide=
as,
>> 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 project=
s
>> 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 bui=
lt
>> 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=E7as para ser o melhor engenh=
eiro
> que eu puder ser"
>



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