On 2/17/11 7:19 AM, Ricardo Aráoz wrote:
> We have three possible (as far as I see it) paths here :
>
> - help will come from docstrings
> - docstrings will be written thinking in framework developers
> - docstrings will be written thinking in framework users
>
> - help will come from help documentation which is written for
> framework users and not necessarily the same as the docstrings.
Since 2004, we've intended docstrings to be targeted to framework users, and
comments
to be targeted to framework developers.
API docs can and should be auto-generated from method signatures and docstrings.
If docstrings get a bit longer for better API docs, I'm all for it. If they
start
looking like JavaDoc or the page-long method headers I used to put in my own
VFP
code, then I'm against it. If we need more for API docs, how about defining a
convention like creating files alongside the source files for extra
documentation:
dabo/ui/uiwx/dButton__xdoc.py:
{{{
from dButton import dButton
dButton.__doc__ += """
lots of extra documentation here
"""
}}}
After you import this file, the dButton docs should reflect both the terse and
expanded versions.
Just an idea.
Paul
_______________________________________________
Post Messages to: [email protected]
Subscription Maintenance: http://leafe.com/mailman/listinfo/dabo-users
Searchable Archives: http://leafe.com/archives/search/dabo-users
This message: http://leafe.com/archives/byMID/[email protected]
