documenting global variables with rdoc

[Paul Brannan]

Perhaps I shouldn't be using global variables to begin with, but I have
an extension that defines two virtual (global) variables (let's call
them $foo and $bar for the sake of argument). How can I document them?

Both are of type Foo, and I considered documenting them with the
documentation for class Foo (this is what the documentation writers for
the ruby interpreter seem to have done with $_ and $~ and the like). Is
there another way?

Thanks,

Paul

 

[Dave Thomas]

Perhaps I shouldn't be using global variables to begin with, but I have
an extension that defines two virtual (global) variables (let's call
them $foo and $bar for the sake of argument). How can I document them?

Sorry - I'm not sure _how_ to document them (or, to be more precise,
where to document them, and how to recognize them). The where part
isn't trivial: global variables don't have a particular home in the
hierarchy. The recognizing part is tricky too: in order to be able to
associate a comment with them, there has to be some kind of pseudo
declaration, but globals don't need one.

I'm definitely open to suggestions, though.


Cheers

Dave

 

[Paul Brannan]

Sorry - I'm not sure _how_ to document them (or, to be more precise,
where to document them, and how to recognize them). The where part
isn't trivial: global variables don't have a particular home in the
hierarchy. The recognizing part is tricky too: in order to be able to
associate a comment with them, there has to be some kind of pseudo
declaration, but globals don't need one.

I'm definitely open to suggestions, though.

I sorta imagined a special markup tag to indicate that I want to
document a global variable. I could include this in any comment in my
file.

As for what to do with this, I was thinking, what is the difference
semantically between a global variable and a pair of toplevel methods
$global() and $global=() that cannot be redefined in derived classes?
(In fact, virtual and hooked variables defined in extensions acutally
are methods that are called by referencing a global identifier). So
they could be documented as methods, even thought that might be a little
confusing.

Whether to document the globals as methods or inline with the comment
their documentation is contained in could be a switch specified on the
command-line.

A similar tag could be used for documenting dynamically-generated
methods. Obviously I haven't thought through all the details, though.

Paul