Replacing RDoc: what do you want to see?

(Anonymous Coward) #1

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

···

--
template<typename duck>
void quack(duck& d) { d.quack(); }

(James Britt) #2

ES wrote:

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) #3

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.

--
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca

(mathew) #4

ES wrote:

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

(James Britt) #5

Austin Ziegler 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.

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

···

On 8/27/05, ES <ruby-ml@magical-cat.org> wrote:

--

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) #6

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

···

On 27 Aug 2005, at 13:46, Austin Ziegler wrote:

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.

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.

--
Eric Hodel - drbrain@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

(Austin Ziegler) #7

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.

--
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca