Slightly off topic, I do have an interfaces gripe... or question, perhaps... If interfaces are to be used for API documentation, one thing they lack in the scarecrow interfaces implementation is the ability to declare constants in the interface like you would in IDL or Java. DOM node type numbers are a good example of what comes to my mind in this case. Any thoughts on how you would document objects that fulfill this sort of interface with scarecrow interfaces? Sean -----Original Message----- From: Amos Latteier [mailto:amos@zope.com] Sent: Tuesday, October 02, 2001 10:52 AM To: k_vertigo@yahoo.com Cc: zope@zope.org Subject: Re: [Zope] interfaces and help system kapil wrote:
is there a way to register interfaces as part of the online help system?
Yes there is, though it is an experimental feature which isn't currently being used anywhere in Zope. If you register an API help topic Zope will not only recognize classes but interfaces in the .py file. You don't have to do anything special just use context.registerHelp() in your product's initialization function. The relevant code is in HelpSys/APIHelpTopic.py BTW, in the future, I think all API docs should be done with interfaces. I have a proposal in the fishbowl for this. http://dev.zope.org/Wikis/DevSite/Projects/APIDocs/ Sadly this project is currently on hold. The reason is that we don't have enough time to work on it. I'd still like to see this project revived, once we have resources available to work on it. -Amos -- Amos Latteier amos@zope.com Zope Corporation http://www.zope.com/ _______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
sean.upton@uniontrib.com wrote:
Slightly off topic, I do have an interfaces gripe... or question, perhaps... If interfaces are to be used for API documentation, one thing they lack in the scarecrow interfaces implementation is the ability to declare constants in the interface like you would in IDL or Java. DOM node type numbers are a good example of what comes to my mind in this case. Any thoughts on how you would document objects that fulfill this sort of interface with scarecrow interfaces?
While we normally think of interfaces as describing classes, they can also be used to describe modules. Interfaces can also have attributes as well as methods. So to take your DOM example, you could use an interface with attributes to describe a DOM module interface. We should remember though that interfaces alone are probably never enough to describe complex systems. It's often helpful to have framework documentation that gives background information and examples. -Amos -- Amos Latteier amos@zope.com Zope Corporation http://www.zope.com/
Scarecrow Interfaces can not have attributes at the moment. The interface system chokes on them. This is what stopped CoreSessionTracking from working with Zope 2.4.1. I asked about this, and I was told that it was more or less on purpose. :-( ----- Original Message ----- From: "Amos Latteier" <amos@zope.com> To: <sean.upton@uniontrib.com> Cc: <zope@zope.org> Sent: Tuesday, October 02, 2001 3:00 PM Subject: Re: [Zope] interfaces and help system
sean.upton@uniontrib.com wrote:
Slightly off topic, I do have an interfaces gripe... or question, perhaps... If interfaces are to be used for API documentation, one thing they lack in the scarecrow interfaces implementation is the ability to declare constants in the interface like you would in IDL or Java. DOM node type numbers are a good example of what comes to my mind in this case. Any thoughts on how you would document objects that fulfill this sort of interface with scarecrow interfaces?
While we normally think of interfaces as describing classes, they can also be used to describe modules. Interfaces can also have attributes as well as methods. So to take your DOM example, you could use an interface with attributes to describe a DOM module interface.
We should remember though that interfaces alone are probably never enough to describe complex systems. It's often helpful to have framework documentation that gives background information and examples.
-Amos
-- Amos Latteier amos@zope.com Zope Corporation http://www.zope.com/
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
participants (3)
-
Amos Latteier -
Chris McDonough -
sean.upton＠uniontrib.com