I am thinking of starting something up to entirely
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.
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.)
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
···
On 8/27/05, ES <ruby-ml@magical-cat.org> wrote:
I am thinking of starting something up to entirely
replace (not fix) RDoc, so I need some input.
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.
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.
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.
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.
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
···
On 8/27/05, Eric Hodel <drbrain@segment7.net> wrote:
If RDoc is broken, people should file bugs so that us maintainers can
fix things.