On 6 October 2016 at 00:29, Nyall Dawson <[email protected]> wrote: > First issue: with doxygen comments, do we go: > > 1. > > /** > * my awesome function > * does something cool > */ > > or > > 2. > > /** my awesome function > * does something cool > */
+1 for option 1) (with strk proposal) > 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" +1 for option 1) > and does this apply to both the descriptions AND extra tags like > notes? Or do different rules apply? both for consistency > 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... I vote for self explanatory var names and less time spent documenting obvious stuffs. Btw if a param description is necessary... to leave doxy quite, add the description for all. I don't remember many cases where vars names does not explain their meaning. If a var has a polysemantic meaning, probably the api have to be redefined. > That is all > > Nyall cheers Luigi Pirelli ************************************************************************************************** * Boundless QGIS Support/Development: lpirelli AT boundlessgeo DOT com * LinkedIn: https://www.linkedin.com/in/luigipirelli * Stackexchange: http://gis.stackexchange.com/users/19667/luigi-pirelli * GitHub: https://github.com/luipir * Mastering QGIS: https://www.packtpub.com/application-development/mastering-qgis ************************************************************************************************** _______________________________________________ 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
