Changeset 9179d0a in mainline for generic/src/synch/waitq.c

Timestamp:

2006-04-27T17:13:49Z (19 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

040e4e9

Parents:

eaa202a

Message:

Add some @file doxygen comments and improve already existing comments.

File:

• generic/src/synch/waitq.c (modified) (2 diffs)

generic/src/synch/waitq.c

@@ -25 +25 @@
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * @file        waitq.c
+ * @brief       Wait queue.
+ *
+ * Wait queue is the basic synchronization primitive upon all
+ * other synchronization primitives build.
+ *
+ * It allows threads to wait for an event in first-come, first-served
+ * fashion. Conditional operation as well as timeouts and interruptions
+ * are supported.
  */
 
@@ -161 +173 @@
  * @param nonblocking Blocking vs. non-blocking operation mode switch.
  *
- * If @usec is greater than zero, regardless of the value of @nonblocking,
+ * If usec is greater than zero, regardless of the value of nonblocking,
  * the call will not return until either timeout or wakeup comes.
  *
- * If @usec is zero and @nonblocking is zero (false), the call
+ * If usec is zero and @nonblocking is zero (false), the call
  * will not return until wakeup comes.
  *
- * If @usec is zero and @nonblocking is non-zero (true), the call will
+ * If usec is zero and nonblocking is non-zero (true), the call will
  * immediately return, reporting either success or failure.
  *
- * @return Returns one of: ESYNCH_WOULD_BLOCK, ESYNCH_TIMEOUT,
- *         ESYNCH_OK_ATOMIC, ESYNCH_OK_BLOCKED.
- *
- * ESYNCH_WOULD_BLOCK means that the sleep failed because at the time
+ * @return      Returns one of: ESYNCH_WOULD_BLOCK, ESYNCH_TIMEOUT,
+ *              ESYNCH_OK_ATOMIC, ESYNCH_OK_BLOCKED.
+ *
+ * @li ESYNCH_WOULD_BLOCK means that the sleep failed because at the time
  * of the call there was no pending wakeup.
  *
- * ESYNCH_TIMEOUT means that the sleep timed out.
- *
- * ESYNCH_INTERRUPTED means that somebody interrupted the sleeping thread.
- *
- * ESYNCH_OK_ATOMIC means that the sleep succeeded and that there was
+ * @li ESYNCH_TIMEOUT means that the sleep timed out.
+ *
+ * @li ESYNCH_INTERRUPTED means that somebody interrupted the sleeping thread.
+ *
+ * @li ESYNCH_OK_ATOMIC means that the sleep succeeded and that there was
  * a pending wakeup at the time of the call. The caller was not put
  * asleep at all.
  * 
- * ESYNCH_OK_BLOCKED means that the sleep succeeded; the full sleep was 
+ * @li ESYNCH_OK_BLOCKED means that the sleep succeeded; the full sleep was 
  * attempted.
  */