[Bug 722] New: Orocos should annotate thread-safety/real-timeness in API docs


Summary: Orocos should annotate thread-safety/real-timeness in
API docs
Product: RTT
Version: rtt-trunk
Platform: All
OS/Version: All
Status: NEW
Severity: minor
Priority: P3
Component: Website - Documentation
AssignedTo: orocos-dev [..] ...
ReportedBy: peter [..] ...
CC: orocos-dev [..] ...
Estimated Hours: 0.0

We should annotate most functions in RTT to indicate if they are real-time or
not and thread-safe or not.

Doxygen allows to define custom @ tags, which are expanded to what you define.
We could introduce:

tag : User visible description in API docs.

@nrt : Never real-time.
@art : Always real-time.
@crt : Conditionally real-time (depends on (template) arguments of

@nts : Not thread-safe (User needs to guard with locks).
@ats : Always thread-safe
@cts : Conditionally thread-safe (depends on (template) arguments of
@lts : Limited thread-safe. Only a limited number of threads may access this
class/function at the same time.

Some of these will require additional documentation in the function or class
description to describe the conditions or limitations.

They can easily be added as we're going and it could even allow some form of
checking (for example, an @art tagged function calling an @nrt function).


[Bug 722] Orocos should annotate thread-safety/real-timeness in


Peter Soetens <peter [..] ...> changed:

What |Removed |Added
Component|Website - Documentation |RTT
Version|rtt-trunk |unspecified
Product|RTT |Toolchain

--- Comment #1 from Peter Soetens <peter [..] ...> 2010-12-21 10:58:15 ---
Moved this bug to 2.x line.