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.

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