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

People,

Thanks for the comments. But now is time to DO! Who is able to get involved=
?
Do this kind of decision needs the approval of MATZ?

Charles, could you briefly yours plans?

I'm very decided to help the community improving a new documentation system
(or improving YArD)! And now is time to plan.


Regards,
Luiz Vitor.

On Mon, Feb 2, 2009 at 3:58 AM, Charles Oliver Nutter <
[e-mail]> wrote:

> I'd love to see a documentation system similar to what python has, and YA=
RD
> comes pretty close. Since we haven't been able to get any sort of annotat=
ion
> 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 return=
ed
>> 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 structure=
d
>> 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] <mailto:
>> [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 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, <[e-mail]
>>    <mailto:[e-mail]>> wrote:
>>
>>        Quoting Austin Ziegler <[e-mail]
>>        <mailto:[e-mail]>>:
>>
>>            On Sun, Feb 1, 2009 at 10:51 AM, Luiz Vitor Martinez Cardoso
>>            <[e-mail] <mailto:[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 Rub=
y
>>            currently offers), and what do you mean by "better" (that
>>            is, what do
>>            you feel that Ruby currently lacks).
>>
>>            -austin
>>            --
>>            Austin Ziegler * [e-mail]
>>            <mailto:[e-mail]> * http://www.halostatue.ca/
>>                          * [e-mail]
>>            <mailto:[e-mail]> * http://www.halostatue.ca/feed=
/
>>                          * [e-mail] <mailto:[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
>>        "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=E7as para ser o
>>    melhor engenheiro que eu puder ser"
>>
>>
>>
>>
>> --
>> Yehuda Katz
>> Developer | Engine Yard
>> (ph) 718.877.1325
>>
>
>
>


--=20
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 d=
e
que eu vou lutar com todas as minhas for=E7as para ser o melhor engenheiro =
que
eu puder ser"