Re: [Zope-dev] Strange permissions in the (built-in) API reference

2000-10-12 Thread Michel Pelletier

KevinL wrote:
 
  Michel Pelletier wrote
  Dieter Maurer wrote:
  3. Jim is working on formal interface support for python and he's
  thinking hard about it, we definatly didn't want to think hard about it
  and then turn out we came up with a bad answer, the existing API docs
  are just that, docs, not interfaces.  When format interfaces come about,
  API docs will probably be converted to that format.
 
 As in mods to python to give it interface support?  Is that discussion taking
 place anywhere public? 

It already did way back in the day shimmery dream sequence

http://www.zope.org/Members/jim/PythonInterfaces/Summary


 It's suddenly become an issue for me, for a
 non-related project...
 
 KevinL

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )




Re: [Zope-dev] Strange permissions in the (built-in) API reference

2000-10-11 Thread Michel Pelletier

Dieter Maurer wrote:
 
 Recently, I read the "Interface Wiki". It covers most of
 the methods contained in the API and its permission descriptions
 made a very solid impression. Maybe, you can start from these
 descriptions.

The Interfaces Wiki is actually where all the API documention did come
from.  Are there inconsistencies?
 
 It might also not be optimal wrt. maintainability
 that the modules, their classes and their methods with
 the respective docstrings have been recreated
 just for API documentation purposes.
 Probably, it would be preferable to use the docstrings
 and the method prototypes from the source directly.
 You might still want to control with methods are described
 in the API and in which order.
 Personally, I would control this, too, inside the source
 documentation (a la javadoc), but I can imagine that an
 external configuration might be advantageous.

Yes, there are pros and cons on both sides, and Amos, Jim and I had some
long converstations about this very subject.  We decided to go with
seperate documentation instead of autogenerating it because:

1. An interface should be a contract, not just an artifact of the code.

2. Python, being without first class support for interfaces, has no
clear way of spelling an interface of a class.

3. Jim is working on formal interface support for python and he's
thinking hard about it, we definatly didn't want to think hard about it
and then turn out we came up with a bad answer, the existing API docs
are just that, docs, not interfaces.  When format interfaces come about,
API docs will probably be converted to that format.

Thanks for the comments!

-Michel

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )




[Zope-dev] Strange permissions in the (built-in) API reference

2000-10-09 Thread Dieter Maurer

I have just thouroughly looked through the API reference
which is built in Zope 2.2.2.

I found many strange permission statements, e.g.:

  * all methods of "PropertySheets" can only be used from Python

  * while "PropertySheet.propertyItems" can be used with
permission "Access Contents Information",
"PropertySheet.getProperty" can be used from Python only

  * "ObjectManagerItem.restrictedTraverse" can be used
from Python only

  * some permission are given as "XXX" (e.g.
"ObjectManagerItem.this")


I wonder, if this is caused by the API reference being shipped
with "data.fs.in" (which, in my case, is old, at least 2.2.1).

If this would be the case, then it might be better to have such
documentation outside in the file system, as "data.fs" tends
to taken over from older installations to newer ones.


Besides, there are many small problems with structured text.
One particular instance is the removal of default arguement
values '', caused by the interpretation of "'".


Dieter

___
Zope-Dev maillist  -  [EMAIL PROTECTED]
http://lists.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope-announce
 http://lists.zope.org/mailman/listinfo/zope )