so you're actually talking about formatting comments for a documentation
extractor like Javadoc/epydoc/naturaldocs?
-d
On 07/08/2010 03:00 PM, Sebastian Benthall wrote:
On Thu, Jul 8, 2010 at 10:43 AM, David Winslow <[email protected]
<mailto:[email protected]>> wrote:
On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
One thing I can think of right off the bat that is comments on
the Python stuff in particular. I think it would be good to
adopt a standard for that and try to stick to it.
I'm not sure I understood this; it is a vague response to a long
email. Are you saying that we should have some coding guidelines
for patches to the Python code that stipulate comment formatting?
Yes. Precisely.
http://docs.codehaus.org/display/GEOT/5.1.1+Coding+Conventions
http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
http://trac.openlayers.org/wiki/CodingStandards
Yes. The reason why I mentioned Python specifically was because I
thought we had more or less de facto had the OpenLayers commenting
standards for the JavaScript (though I suppose we should decide
whether we should use those or the Ext ones, which if I recall
correctly are different in order to support API doc generation from
the restructured text comments) and (I had assumed) the GeoServer
standards for the GeoServer-y parts.
Adopting the Django coding style for the Python bits sounds like a
great idea for me.
I notice that it though it provides something of a style guide for
docstrings, though, it doesn't say much more than "use action words."
I guess that's better than nothing. We could go with that and then
adjust later if its not sufficient.
Along these lines, I'd also be interested in having some browsable
API documentation once dev.geonode.org <http://dev.geonode.org> is
available to us for such things. A certain level of documentation
coverage could be another factor in patch acceptability.
--
David Winslow
OpenGeo - http://opengeo.org/
--
Sebastian Benthall
OpenGeo - http://opengeo.org
