doesn't support constants

[Jelmer Vernooij]

integer and string contents are ignored at the moment, it'd be nice if they were documented. This would help with bug 410000 and with C inspection (though it's also possible to ignore explicitly constants of course).

Does this seem like a reasonable feature, and would implementing it this just be a matter of adding another subclass of pydoctor.model.Documentable?

[Jelmer Vernooij (jelmer)]

s/ignore explicitly/explicitly ignore/

[Michael Hudson-Doyle (mwhudson)]

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.

[Jelmer Vernooij (jelmer)]

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.

Cheers,

Jelmer

[Michael Hudson-Doyle (mwhudson)]

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

[Jean-Paul Calderone (exarkun)]

Is this related to supporting module variables as link targets? It seems that presently even something documented with @var cannot be the target of L{}.

[Glyph Lefkowitz (glyph)]

See also this Twisted bug: <http://twistedmatrix.com/trac/ticket/6196>.

[Michael Hudson-Doyle (mwhudson)]

Jean-Paul Calderone <email address hidden> writes:

> Is this related to supporting module variables as link targets? It
> seems that presently even something documented with @var cannot be the
> target of L{}.

It actually seems that things at module level documented with @var are
not present in the rendered page currently... which doesn't seem like it
was what I intended.

[Michael Hudson-Doyle (mwhudson)]

I've fixed that problem in r588. I don't know if it's worth starting to recognise constant assignments at module level and reporting them as undocumented... might be interesting. So I'll leave this bug open for now.