Extending rdoc for custom accessors

ruby-talk
1

My code has some things that work a bit like “attr_reader” et al, but of
course rdoc doesn’t know about them. Is there an easy way to extend rdoc
to handle such things?

2

unsubscribe

···

-----Original Message-----
From: Joel VanderWerf [mailto:vjoel@PATH.Berkeley.EDU]
Sent: Monday, May 26, 2003 7:14 PM
To: ruby-talk ML
Subject: extending rdoc for custom accessors

My code has some things that work a bit like “attr_reader” et al, but of

course rdoc doesn’t know about them. Is there an easy way to extend rdoc

to handle such things?

3

Joel VanderWerf wrote:

My code has some things that work a bit like “attr_reader” et al, but of
course rdoc doesn’t know about them. Is there an easy way to extend rdoc
to handle such things?

That depends on what you’d expect in terms of the resulting output.
Making the parser pluggable is pretty easy: you could write an extension
that handled stuff that matched a regexp you provided, and I’d call you
when that regexp hit in the right context.

However, unless you were satisfied with one of the existing output
fields, you’d also need to extend the output formatters to add new
sections to the generated HTML/XML/etc. This might be messier.

So, so summarize: if you want your accessors to appear in the standard
accessors section, it’s easy. otherwise it’s harder.

Cheers

Dave

4

Dave Thomas wrote:

Joel VanderWerf wrote:

My code has some things that work a bit like “attr_reader” et al, but
of course rdoc doesn’t know about them. Is there an easy way to extend
rdoc to handle such things?

That depends on what you’d expect in terms of the resulting output.
Making the parser pluggable is pretty easy: you could write an extension
that handled stuff that matched a regexp you provided, and I’d call you
when that regexp hit in the right context.

However, unless you were satisfied with one of the existing output
fields, you’d also need to extend the output formatters to add new
sections to the generated HTML/XML/etc. This might be messier.

So, so summarize: if you want your accessors to appear in the standard
accessors section, it’s easy. otherwise it’s harder.

Actually, the caller sees the accessors just like any other accessors,
so the easy approach will work for me. Is there anything I can do?

5

Joel VanderWerf wrote:

So, so summarize: if you want your accessors to appear in the standard
accessors section, it’s easy. otherwise it’s harder.

Actually, the caller sees the accessors just like any other accessors,
so the easy approach will work for me. Is there anything I can do?

OK - I’ve added an --accessor option; check out the latest CVS.

rdoc --accessor db_opt,option,param  fred.rb

or
rdoc -A db_opt,option,param fred.rb

will accept stuff like

class Mine
   db_opt :buffer_size, :pool
   param  :name
   option :line_size, :protocol

and report them alongside normal attributes. You can have multiple
–accessor parameters.

Cheers

Dave

6

Dave Thomas wrote:

OK - I’ve added an --accessor option; check out the latest CVS.

That looks perfect. I’ll check it out asap.

7

Joel VanderWerf wrote:

Dave Thomas wrote:

OK - I’ve added an --accessor option; check out the latest CVS.

That looks perfect. I’ll check it out asap.

Yep, it does what I need.

Maybe someday there could be an option to set the letters, like “R”,
“W”, “RW”, in place of the “?” that shows up now. I’d like to use custom
letters, in fact. But being able to list the accessors with comment text
is the main thing.

Thanks, Dave!

8

Joel VanderWerf wrote:

Maybe someday there could be an option to set the letters, like “R”,
“W”, “RW”, in place of the “?” that shows up now. I’d like to use custom
letters, in fact. But being able to list the accessors with comment text
is the main thing.

Your wish…

In the latest CVS, you can now say

rdoc --accessor option=ro,param=set fred.rb

If fred.rb contains

option :field1
param :field2, :field 3
attr_reader :field4

It’ll be documented as

field1: [ro]
field2: [set]
field3: [set]
field4: [r]

Cheers

Dave

9

Dave Thomas wrote:

Joel VanderWerf wrote:

Maybe someday there could be an option to set the letters, like “R”,
“W”, “RW”, in place of the “?” that shows up now. I’d like to use
custom letters, in fact. But being able to list the accessors with
comment text is the main thing.

Your wish…

In the latest CVS, you can now say

rdoc --accessor option=ro,param=set fred.rb

Very nice :slight_smile:

10

Dave Thomas wrote:

Joel VanderWerf wrote:

Maybe someday there could be an option to set the letters, like “R”,
“W”, “RW”, in place of the “?” that shows up now. I’d like to use
custom letters, in fact. But being able to list the accessors with
comment text is the main thing.

Your wish…

In the latest CVS, you can now say

rdoc --accessor option=ro,param=set fred.rb

If fred.rb contains

option :field1
param :field2, :field 3
attr_reader :field4

It’ll be documented as

field1: [ro]
field2: [set]
field3: [set]
field4: [r]

Cheers

Dave

WOW!! Very quick response from a OSS author! Very impressive!

Two new features added by request each within 8 hours of being requested!

I’ll go and check out the newest version asap. Dave, you rox!

/Anders

···

–
dc -e
4ddod3dddn1-89danrn10-dan3+ann6dan2an13dn1+dn2-dn3+5ddan2/9+an13nap