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
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
On Jul 22, 2004, at 15:38, Paul Brannan wrote:
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?
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
On Fri, Jul 23, 2004 at 10:30:00AM +0900, Dave Thomas wrote:
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.