Re: [Zope-dev] Strange permissions in the (built-in) API reference
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 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
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 )
Re: [Zope-dev] Strange permissions in the (built-in) API reference
Dieter Maurer wrote: > > 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 As a reminder, could you sumbit these to the collector? I can fix the documentation bugs but what permissions should be what is outside my scope, and would probably require some thought from Brian or Jim or someone more aware of the security details. > * some permission are given as "XXX" (e.g. > "ObjectManagerItem.this") I'll fix this for the next release. > 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. This documentation is on the filesystem, for example all of the OFS objects' API references are in lib/python/Products/OFSP/help. They are python modules that get turned into documetation when Products get registered. > Besides, there are many small problems with structured text. > One particular instance is the removal of default arguement > values '', caused by the interpretation of "'". Hmmm... ok we'll think about that. Thanks, -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 )
