Pretty sure I'm not the only OCD member of the QGIS team who hates inconsistency and is affected by these issues ;)
First issue: with doxygen comments, do we go: 1. /** * my awesome function * does something cool */ or 2. /** my awesome function * does something cool */ Second issue: do we 1. Write in full sentences, with initial caps + trailing "." eg "Does something cool to QGIS." or 2. Use fragments, with no caps or ".", eg "does something cool" and does this apply to both the descriptions AND extra tags like notes? Or do different rules apply? Third issue: Do we document parameters? I've been doing this because doxygen requires an "all or nothing" approach, eg you can't only document the tricky parameters and leave obvious ones out. This ends up in a lot of obvious "@param fillColor new fill color" type docs, which seem redundant. I generally do this so that the occasional trickier parameter is easier to document (eg "@param symbol new symbol style for fill, ownership is transferred to the renderer"). But I often wonder if everyone is wondering what the heck I'm doing writing docs like "@param width new width", so I'm curious to hear other opinions... That is all Nyall _______________________________________________ Qgis-developer mailing list [email protected] List info: http://lists.osgeo.org/mailman/listinfo/qgis-developer Unsubscribe: http://lists.osgeo.org/mailman/listinfo/qgis-developer
