Replacing RDoc: what do you want to see?

[ES]

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.

So, make a list.

E

 

[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

http://www.ruby-doc.org


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.)


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

 

[Austin Ziegler]

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.

-austin
--=20
Austin Ziegler * (e-mail address removed)
* Alternate: (e-mail address removed)

 

[James Britt]

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.



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

 

[Eric Hodel]

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

 

[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
--=20
Austin Ziegler * (e-mail address removed)
* Alternate: (e-mail address removed)