On 6 October 2016 at 08:51, Matthias Kuhn <[email protected]> wrote: > I've been thinking about the same. And have some opinions. > > On 06/10/16 00:29, Nyall Dawson wrote: >> 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 >> */ > My vote clearly goes to #2. > > The reason is that it adds additional space between one method and the > comment of the next method (which are logically different parts). > This helps (me) to be able scroll through headers quicker and still spot > method names.
Do you mean #1 here? https://github.com/qgis/QGIS/commit/b642c3ff5ede2cae88d30f881f7ae7c99e1bfccc#diff-aaa596c71ada12dd18c410856a8f4f77R64 would lead me to think you prefer that style? > > +1 to 2. > >> 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? > > The advantage of full sentences is, that they always work and can be > used consistently. And a quick look at the Qt docs shows that they seem > to be doing the same. > > +0 on 1. > >> 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 like self-explanatory names and I don't like stating the obvious. > Therefore I'm rather in the camp "if a parameter name is intuitive, I > don't want to spend some of my attention and screen space on parsing > useless documentation for it". > > I don't have a problem with only including params where there is useful > additional info (also if 4 of these 5 parameters are not of this kind), > same for return. Documenting parameters for setters and return values > for getters is mostly redundant. Agree - BUT doxygen doesn't allow this and will throw a warning. So for any method with at least one parameter which needs useful docs it requires all parameters to be documented. One solution could be to just go: /** * My function. * @param color * @param size * @param p magic number. If p > 5 then qgis will run faster, if p = 5 then qgis 2.0 api will be used, if p< 5 then output will be scaled to painter's dpi. */ Ie put the @param's for obvious parameters to keep doxygen happy but leave them empty. That would help draw attention to important parameters. Nyall > > But I can totally understand if someone once to keep this consistent. > > Matthias > >> >> >> 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 > > > _______________________________________________ > 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 _______________________________________________ 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
