No, I was actually talking about Python comments more generally. However, it would be a good idea probably to choose between either the OpenLayers or Ext coding guidelines. Documentation extraction is one issue to think about for those.
On Thu, Jul 8, 2010 at 3:06 PM, David Winslow <[email protected]> wrote: > 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]>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 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 > > > -- Sebastian Benthall OpenGeo - http://opengeo.org
