Replacing RDoc: what do you want to see?
ES
replace (not fix) RDoc, so I need some input.
There is only so much data to be gathered from the
source code and RDoc is fairly good at that. What
it is not good at is keeping things simple while
producing a usable data structure. Those are things
that would be automatically corrected. Are there
any other 'mechanical' things that need to be fixed?
The main task would probably be to revise the format
of the documentation itself: allow 'keywords' for a
return value, parameters, examples and so on to build
more meaningful and consistent documentation while
keeping the format as natural as possible. Any good
requests for this part?
The third thing is migration... should probably allow
converting to any new documentation format by just
running a script or then support the old format out
of the box.
So, make a list.
E
--
template<typename duck>
void quack(duck& d) { d.quack(); }
James Britt
> On 8/27/05, ES <rub...@magical-cat.org> wrote:
>
>>I am thinking of starting something up to entirely
>>replace (not fix) RDoc, so I need some input.
>
>
> fixed. If this means that you create an implementation that replaces
> the current one while keeping the same interface and it's of a
> high-enough quality that Matz accepts it into the core, then more
> power to you. However, if it isn't going to make it into the core,
> then I think that it's a bit of a distraction and you'd be better off
> working with the RDoc maintainers (and possibly seeing about becoming
> one yourself) to fix what's wrong with RDoc.
I don't entirely disagree with this, but I don't buy the "distraction"
argument. If RDoc and "ES-doc" are destined for different paths, so be
it. I'm happy to have alternatives for extraction useful information
from source code. Choice is good.
I've spent enough time trying different approaches to custom parsing the
ri yml files, with unsatisfactory results, that I heartily encourage
people to try their hand at rdoc alternatives and offer up what they find.
James
--
http://www.ruby-doc.org - The Ruby Documentation Site
http://www.rubyxml.com - News, Articles, and Listings for Ruby & XML
http://www.rubystuff.com - The Ruby Store for Ruby Stuff
http://www.jamesbritt.com - Playing with Better Toys
James Britt
> I am thinking of starting something up to entirely
> replace (not fix) RDoc, so I need some input.
Have you considered discussion this in the ruby-doc mailing list? There
have been assorted discussion there on rj, ri.next, and so on.
You can find info about the list at
As for feature requests, the ability to rdoc/ri new files while not
risking the munging of existing rdoc/ri data sets.
(Incidentally, are you planning on replacing ri in the process? It
seems that an ri alternative would be a natural thing add, even if you
are not targeting that.)
Eric Hodel
> On 8/27/05, ES <rub...@magical-cat.org> wrote:
>
>> I am thinking of starting something up to entirely
>> replace (not fix) RDoc, so I need some input.
>>
>
> Honestly, I don't want to see RDoc replaced. I *do* want to see it
> fixed. If this means that you create an implementation that replaces
> the current one while keeping the same interface and it's of a
> high-enough quality that Matz accepts it into the core, then more
> power to you. However, if it isn't going to make it into the core,
> then I think that it's a bit of a distraction and you'd be better off
> working with the RDoc maintainers (and possibly seeing about becoming
> one yourself) to fix what's wrong with RDoc.
If RDoc is broken, people should file bugs so that us maintainers can
fix things.
http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
--
Eric Hodel - drb...@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04
Austin Ziegler
> If RDoc is broken, people should file bugs so that us maintainers can
> fix things.
Agreed. There are some things that I'd like to see done, but nothing
that bothers me *quite* enough to file anything. Lothar seems to think
that there are bigger problems, but also seems uninterested in filing
bug reports. However, I think that there's a definite suggestion that
the complexity of RDoc might be higher than perhaps it should be, at
least the intermediate forms. The biggest problem that I've seen with
ri -- and again, I haven't checked yet on the bug tracker -- is its
inability to cleanly merge modifications.
-austin
--
Austin Ziegler * halos...@gmail.com
* Alternate: aus...@halostatue.ca
Austin Ziegler
> replace (not fix) RDoc, so I need some input.
Honestly, I don't want to see RDoc replaced. I *do* want to see it
fixed. If this means that you create an implementation that replaces
the current one while keeping the same interface and it's of a
high-enough quality that Matz accepts it into the core, then more
power to you. However, if it isn't going to make it into the core,
then I think that it's a bit of a distraction and you'd be better off
working with the RDoc maintainers (and possibly seeing about becoming
one yourself) to fix what's wrong with RDoc.
-austin
mathew
> I am thinking of starting something up to entirely
> replace (not fix) RDoc, so I need some input.
Any replacement for Rdoc will need to accept the same input Rdoc
currently accepts, and produce output that's significantly better.
Otherwise, it won't be worth the pain of migration. It's hard enough to
get programmers to document code to start with (just look at the
standard library!), let alone get them to go back and re-document it.
The biggest problem I've found with Rdoc is that there doesn't seem to
be any easy way to make it generate documentation for methods that are
created at run time. However, to be honest I'd rather see Rdoc fixed to
add a directive for that, rather than a whole new system written.
mathew
--
<URL:http://www.pobox.com/~meta/>
WE HAVE TACOS