From 5ce051e7b8762caa94316ff68c77eb60081589c1 Mon Sep 17 00:00:00 2001
From: Martin Mares <mj@ucw.cz>
Date: Sun, 27 Feb 2011 00:09:13 +0100
Subject: [PATCH] Main: Proofreading docs

---
 ucw/doc/mainloop.txt |  4 ++--
 ucw/mainloop.h       | 26 +++++++++++++++-----------
 2 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/ucw/doc/mainloop.txt b/ucw/doc/mainloop.txt
index 7bcf3fb8..d39a84c1 100644
--- a/ucw/doc/mainloop.txt
+++ b/ucw/doc/mainloop.txt
@@ -41,13 +41,13 @@ Simple programs usually employ the main loop in a straightforward way:
   handles them by calling the appropriate hook functions. These functions
   can of course add new events or modify/delete the existing ones.
 - When the program decides it wants to stop, it calls @main_shut_down(),
-  or alternatively it returns `HOOK_SHUTDOWN` from some hook callback.
+  or alternatively it returns <<enum_main_hook_return,`HOOK_SHUTDOWN`>> from some hook callback.
   Soon after that, @main_loop() returns.
 - Remove all event hooks and call @main_cleanup().
 
 The event structures (like <<struct_main_file,`struct main_file`>>) are
 always allocated by the user, but please touch only the fields marked
-in this documentation with `[*]'. The other fields are used internally;
+in this documentation with `[*]`. The other fields are used internally;
 you should initialize them to zeroes before adding the event and avoid
 accessing them afterwards.
 
diff --git a/ucw/mainloop.h b/ucw/mainloop.h
index 088d769e..4a6fe843 100644
--- a/ucw/mainloop.h
+++ b/ucw/mainloop.h
@@ -89,10 +89,9 @@ void main_teardown(void);
 /**
  * Start the event loop on the current context.
  * It will watch the provided objects and call callbacks.
- * Terminates when someone sets <<var_main_shutdown,`main_shutdown`>>
- * to nonzero, when all <<hook,hooks>> return
- * <<enum_main_hook_return,`HOOK_DONE`>> or at last one <<hook,hook>>
- * returns <<enum_main_hook_return,`HOOK_SHUTDOWN`>>.
+ * Terminates when someone calls @main_shut_down(),
+ * or when all <<hook,hooks>> return <<enum_main_hook_return,`HOOK_DONE`>>
+ * or at last one <<hook,hook>> returns <<enum_main_hook_return,`HOOK_SHUTDOWN`>>.
  **/
 void main_loop(void);
 
@@ -199,13 +198,15 @@ void main_get_time(void);
  * From within the handler functions, you are allowed to call @file_chg() and even
  * @file_del().
  *
- * The return value of a handler function should be either `HOOK_RETRY` or `HOOK_IDLE`.
- * `HOOK_RETRY` signals that the function would like to consume more data immediately
+ * The return value of a handler function should be either <<enum_main_hook_return,`HOOK_RETRY`>>
+ * or <<enum_main_hook_return,`HOOK_IDLE`>>. <<enum_main_hook_return,`HOOK_RETRY`>>
+ * signals that the function would like to consume more data immediately
  * (i.e., it wants to be called again soon, but the event loop can postpone it after
- * processing other events to avoid starvation). `HOOK_IDLE` tells that the handler
- * wants to be called when the descriptor becomes ready again.
+ * processing other events to avoid starvation). <<enum_main_hook_return,`HOOK_IDLE`>>
+ * tells that the handler wants to be called when the descriptor becomes ready again.
  *
- * For backward compatibility, 0 can be used instead of `HOOK_IDLE` and 1 for `HOOK_RETRY`.
+ * For backward compatibility, 0 can be used instead of <<enum_main_hook_return,`HOOK_IDLE`>>
+ * and 1 for <<enum_main_hook_return,`HOOK_RETRY`>>.
  *
  * If you want to read/write fixed-size blocks of data asynchronously, the
  * <<blockio,Asynchronous block I/O>> interface could be more convenient.
@@ -262,7 +263,7 @@ void file_del(struct main_file *fi);
  * and writes for you.
  *
  * You just create <<struct_main_block_io,`struct main_block_io`>> and call
- * @block_io_add() on it, which sets up some `main_file`s internally.
+ * @block_io_add() on it, which sets up some <<struct_main_file,`main_file`>>s internally.
  * Then you can just call @block_io_read() or @block_io_write() to ask for
  * reading or writing of a given block. When the operation is finished,
  * your handler function is called.
@@ -272,7 +273,7 @@ void file_del(struct main_file *fi);
  * (except that it gets added and deleted at the right places), feel free
  * to adjust it from your handler functions by @block_io_set_timeout().
  * When the timer expires, the error handler is automatically called with
- * `BIO_ERR_TIMEOUT`.
+ * <<enum_block_io_err_cause,`BIO_ERR_TIMEOUT`>>.
  ***/
 
 /** The block I/O structure. **/
@@ -384,6 +385,9 @@ struct main_hook {
  *   This will cause calling of all the hooks again soon.
  * - `HOOK_DONE` -- The loop will terminate if all hooks return this.
  * - `HOOK_SHUTDOWN` -- Shuts down the loop.
+ *
+ * The `HOOK_IDLE` and `HOOK_RETRY` constants are also used as return values
+ * of file handlers.
  **/
 enum main_hook_return {
   HOOK_IDLE,
-- 
2.39.2