Function descriptions: descriptive-style or imperative-style?

[Sebastian Huber]

Hello,

I worked a bit on Python development guidelines this week and noticed 
that our Doxygen style guide is not really clear if function 
descriptions should be in descriptive-style or imperative-style:

https://docs.rtems.org/branches/master/eng/coding-doxygen.html#function-declarations

The example "Sends a message to the message queue." suggests that it 
should be descriptive-style. In the RTEMS sources we find also 
imperative-style:

/**
  * @brief Pin the executing thread.
  *
  * @param executing The currently executing thread.
  */

I would like to give an explicit recommendation in the guide. The Google 
Python Style Guide recommends descriptive-style:

http://google.github.io/styleguide/pyguide.html#383-functions-and-methods

PEP 257 recommends imperative-style:

https://www.python.org/dev/peps/pep-0257/

I am in favour of the descriptive-style.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.