[Developers] Plone cleanup
arnima at hafro.is
Fri Jun 18 14:42:09 PDT 2010
Sorry, I didn't know about the proxies.
I think the API Documentation is quite functional as it is now. People
looking for ADMB references will click 'Documentation' - 'Manuals' and
find a link to the current Doxygen Tree that they can browse.
People that would like to contribute additional API documentation will
click 'Documentation' - 'Developers' - 'API Documentation' and find
detailed instructions on how to go about. In the same place they will find
a link to the current Doxygen tree.
So the documentation itself is not restricted to the 'Developers' section,
only the detailed guidelines on how to write additional documentation.
Hosting the Doxygen tree outside of Plone is a practical thing to do, and
faking it with a proxy doesn't serve any obvious purpose. The Foundation
website can host the newsletter and the Doxygen tree, and both are
prominently linked from the Plone pages.
At the La Jolla meeting, we encouraged core developers with SVN write
access to add Doxygen to existing code anytime, and others to send Doxygen
commented source file updates to Johnoel. Since then, I uploaded
keywords.txt to identify classes and methods that are likely to be looked
up by users.
John made an effort to test both the "Doxygen" and "Javadoc" style. I
agree with him that the default "Doxygen" style works better, and that we
can safely remove all traces of "Javadoc" from the guidelines and
elsewhere. It was a worthwhile test, since we didn't know beforehand which
style would work better with ADMB, or if both were useful.
On Fri, 18 Jun 2010, John Sibert wrote:
> I'm glad to see that the material was not lost, but something is
> definitely broken. As I recall, there were some proxies on the plone
> site that pointed to directories at admb-foundation.org. These proxies
> were probably lost when the NCEAS folks tried to update the hosting or
> when you moved the material to a different directory. Johnoel set them
> up, but I cannot remember what they were. Perhaps Johnoel has some
> insights. Perhaps proxies are a bad idea for this purpose?
> More generally, I'm not sure the API documentation belongs in the
> developers section. In the long run, users should be able to refer to
> the on-line API dox. True, the draft API documentation was created in
> part to generate some feedback, but I have received very few comments
> about the draft. Assuming that few comments are forthcomming, I'm ready
> to conclude that the API docs are OK as is, that we prefer the default
> doxygen style (in lovely ADMB greens), and that we can omit the javadocs
> style from further consideration.
More information about the Developers