[Zope3-dev] Implementation doc strings (was Re: Big import blocks)

[Jim Fulton]

Guido van Rossum wrote:
> [me]

...

> Agreed, though this is a separate issue: things like traverse() or
> getAdapter() currently have no docstrings at all.  This in part
> because Zope 3 isn't finished yet, in part because Jim's philosophy
> about documenting Zope 3 was to try and separate the documentation
> from the code, by putting it in interfaces.  I think I've convinced
> him that it's not wrong to put real documentation in implementation
> docstrings too, now all we need is a sprint to add docstrings to all
> the right places.

I'd like to discuss this a bit. Here are some issues:

- You should be able to look at the interface to find out how to
   use something.

- We want to work well with tools like "help" and "pydoc".

- Duplication is risky. If we put the same doc string in an interface
   and in an implementation, then we have to remember to update the
   documentation in all places.

   Note that there are often multiple implementations of the same
   interface. In many cases, implementations could be in 3rd-party
   products.

   I'm worried that dealing with this duplication will be impractical.

We *could* diplicate the doc strings in the interfaces and each
of the implementations. I'm not sure that this is a good idea.

An alternative would be to update pydoc to be interface aware.
If we could do this, even via a monkey patch, then I think we'd be
in better shape. This could be made to work pretty well.

In any case, we need a convention documenting the
interface implemented in the implementation. This is what we often
do now:

     def getService(self, name):
         "See zope.component.interfaces.IServiceService"

Not everyone likes this and we have applied it inconsistently.
Note that this can work pretty well in conjuction with something like
emacs tags, which makes it pretty easy to jump to the definition of a name.


> One problem I've found with sprints is that often there's a desire to
> move on quickly -- the name suggests this and there's also the issue
> that sprints are bounded in time -- which means that developers
> sometimes don't write docstrings.  I think this is a mistake, and I
> recommend that sprinters try to come up with reasonable docstrings as
> they go.  It's okay if the docstrings aren't perfect or occasionally
> contain typos and incomplete sentences; there's a host of people who
> can fix those.  But if there are *no* docs, the intent of the code can
> only be guessed from its implementation, which is usually
> overspecified (and sometimes underspecified, i.e. incomplete!).

This is a good point. Sprinting is no excuse for bad doc strings
or bad unit tests.

>>The dead chicken right now is not the amount of imports, it's being
>>able to grasp what you need to do, what you need to import, how
>>things work (enough to feel confidant in doing your own work), and
>>of course, ZCML (I still think most new users will spend more of
>>their time getting comfortable with ZCML than with anything else, at
>>least - based on my own experiences).  I'd rather someone tell me
>>what the ObjectHub is, and when, where, and how to use it, than make
>>it easier for me to import.
> 
> 
> Sure.  Getting familiar with ZCML is a separate issue IMO.  Reference
> docs for ZCML are quite easy to obtain (it's all in zope3/doc/zcml/,
> most of which is auto-generated from <description> tags in the meta
> ZCML), but it could use a good tutorial.  I guess the same is true for
> other aspects of "grasping what you need to do".  I'm still grappling
> with this a lot in many places.  I've recently helped Jim write a
> tutorial for adding a service, which ended up containing a lot of
> tutorial material for writing browser views.  This is currently on the
> local-utility-branch branch; I expect that Jim will merge it into the
> trunk soon.

Done.

>  The tutorial will be src/zope/app/services/README.txt.
> Feedback is welcome.

When I get a chance I'll rename this utility.txt with a pointer to that
from readme file.

Jim


-- 
Jim Fulton           mailto:jim@zope.com       Python Powered!
CTO                  (888) 344-4332            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org