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.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
