Comment 4 for bug 685376

On Sun, 05 Dec 2010 23:14:18 -0000, Jelmer Vernooij <email address hidden> wrote:
> On Sun, 2010-12-05 at 22:47 +0000, Michael Hudson-Doyle wrote:
> > I guess it could be supported. I don't know how they would be
> > "documented" beyond their presence.
> >
> > You can always document them using @ivar or :var: or similar.
> It's mainly their presence that I would like to record. An indication
> that they are undocumented would also be useful.

I do have a loose plan to change the model a bit that's vaguely related,
and you've provided me an excuse to brain dump :-)

Currently, Documentables have a document_in_parent_page attribute that
indicates whether the thing being documented should have its own page or
not. I'd like to expand this to be a three-valued thing: its own page,
in the parent page as functions/methods are now and additionally "in the
parents docstring", as :ivar:s and function arguments are now.
Currently zope Attributes are documented differently from :ivar:s and
that's a bit silly. Having function arguments be documentables or at
least some kind of more structured thing would also let us emit warnings
when you document an argument a function doesn't take, something that's
the topic of another bug report I think.

Brain dump over! I think documenting module variables would fit more
naturally into this view of the world than the one we have today.

Cheers,
mwh