[Zope] Precondition

[R. David Murray]

On Sun, 6 Aug 2000, Martijn Pieters wrote:
>   Precondition
> 
>       Allows you to specify a precondition for the File. A precondition is a
>       method or document which is executed before the File is viewed or
>       downloaded. If the precondition raises an exception then the File cannot
>       be viewed. 
> 
> This is from the Help page presented when you click the 'help' button on the
> 'Edit' tab of a 'File' object.

I knew I'd read it somewhere!

First I ran through the help menu, but I must have looked at
File/Image Add and missed File/Image Edit.  Then I looked at an
Image (I had no File objects handy), and when I saw that the help
tab for the Edit, page had no description of precondition, and indeed
that there was no way to set it, I figured the docs for it must
only be in the API section.  But the API section does not discuss
*any* of the call paramters.  So I thought it was undocumented.

Since the code supports preconditions on an Image, is this an interface
error or a design decision (the latter seems more likely)?  If it's
a design decision, shouldn't precondition still be documented in
the Image api help doc?

This is an example of a systematic problem with the (very useful
<grin>) help docs as they stand:  if the API docs implicitly assume
that the parameters are documented in the corresponding management
interface panel then there should at least by a cross link; and if
there are sometimes parameters that are *not* documented on the
manage page, then that needs to be taken into account somehow.

--RDM