<div dir="ltr">Hello,<br><div class="gmail_extra"><br><div class="gmail_quote">2016-10-06 0:29 GMT+02:00 Nyall Dawson <span dir="ltr"><<a href="mailto:nyall.dawson@gmail.com" target="_blank">nyall.dawson@gmail.com</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Pretty sure I'm not the only OCD member of the QGIS team who hates<br>
inconsistency and is affected by these issues ;)<br>
<br>
First issue: with doxygen comments, do we go:<br>
<br>
1.<br>
<br>
/**<br>
 * my awesome function<br>
 * does something cool<br>
 */<br>
<br>
or<br>
<br>
2.<br>
<br>
/** my awesome function<br>
 * does something cool<br>
 */<br></blockquote><div><br></div><div>+1 for the first, more readable :-)<br><br></div><div>CU<br></div><div>Stéphane<br></div><div><br> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Second issue: do we<br>
<br>
1. Write in full sentences, with initial caps + trailing "." eg "Does<br>
something cool to QGIS."<br>
<br>
or<br>
<br>
2. Use fragments, with no caps or ".", eg "does something cool"<br>
<br>
and does this apply to both the descriptions AND extra tags like<br>
notes? Or do different rules apply?<br>
<br>
<br>
Third issue:<br>
<br>
Do we document parameters? I've been doing this because doxygen<br>
requires an "all or nothing" approach, eg you can't only document the<br>
tricky parameters and leave obvious ones out. This ends up in a lot of<br>
obvious "@param fillColor new fill color" type docs, which seem<br>
redundant. I generally do this so that the occasional trickier<br>
parameter is easier to document (eg "@param symbol new symbol style<br>
for fill, ownership is transferred to the renderer"). But I often<br>
wonder if everyone is wondering what the heck I'm doing writing docs<br>
like "@param width new width", so I'm curious to hear other<br>
opinions...<br>
<br>
<br>
That is all<br>
<br>
Nyall<br>
______________________________<wbr>_________________<br>
Qgis-developer mailing list<br>
<a href="mailto:Qgis-developer@lists.osgeo.org">Qgis-developer@lists.osgeo.org</a><br>
List info: <a href="http://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer" target="_blank">http://lists.osgeo.org/<wbr>mailman/listinfo/qgis-<wbr>developer</a><br>
Unsubscribe: <a href="http://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer" target="_blank">http://lists.osgeo.org/<wbr>mailman/listinfo/qgis-<wbr>developer</a></blockquote></div><br><br clear="all"><br>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><a href="http://camptocamp.com/" target="_blank">camptocamp.com</a><br><a href="http://mapfish.org" target="_blank">mapfish.org</a><br></div>
</div></div>