diff mbox series

[006/110] doc: Make OPAL_RTC_READ docs pretty

Message ID 20190531061351.22973-7-stewart@linux.ibm.com
State Accepted
Headers show
Series Big documentation cleanup/expansion | expand

Commit Message

Stewart Smith May 31, 2019, 6:12 a.m. UTC
Signed-off-by: Stewart Smith <stewart@linux.ibm.com>
---
 doc/opal-api/opal-rtc-read-3.rst | 32 ++++++++++++++++++--------------
 1 file changed, 18 insertions(+), 14 deletions(-)
diff mbox series

Patch

diff --git a/doc/opal-api/opal-rtc-read-3.rst b/doc/opal-api/opal-rtc-read-3.rst
index f56cb2c96c5a..e2d492f2e0bf 100644
--- a/doc/opal-api/opal-rtc-read-3.rst
+++ b/doc/opal-api/opal-rtc-read-3.rst
@@ -1,3 +1,5 @@ 
+.. _OPAL_RTC_READ:
+
 OPAL_RTC_READ
 =============
 
@@ -24,15 +26,17 @@  Parameters
 
 Calling
 -------
-Since RTC calls can be pretty slow, OPAL_RTC_READ is likely to first return
-OPAL_BUSY_EVENT, requiring the caller to wait until the OPAL_EVENT_RTC event
+Since RTC calls can be pretty slow, :ref:`OPAL_RTC_READ` is likely to first return
+:ref:`OPAL_BUSY_EVENT`, requiring the caller to wait until the :ref:`OPAL_EVENT_RTC` event
 has been signaled. Once the event has been signaled, a subsequent
-OPAL_RTC_READ call will retrieve the time. Since the OPAL_EVENT_RTC event is
+:ref:`OPAL_RTC_READ` call will retrieve the time. Since the :ref:`OPAL_EVENT_RTC` event is
 used for both reading and writing the RTC, callers must be able to handle
-the event being signaled for a concurrent in flight OPAL_RTC_WRITE rather
+the event being signaled for a concurrent in flight :ref:`OPAL_RTC_WRITE` rather
 than this read request.
 
-The following code is one way to correctly issue and then wait for a response: ::
+The following code is one way to correctly issue and then wait for a response:
+
+.. code-block:: c
 
     int rc = OPAL_BUSY_EVENT;
     while (rc == OPAL_BUSY_EVENT) {
@@ -41,31 +45,31 @@  The following code is one way to correctly issue and then wait for a response: :
 	     opal_poll_events(NULL);
     }
 
-Although as of writing all OPAL_RTC_READ backends are asynchronous, there is
-no requirement for them to be - it is valid for OPAL_RTC_READ to immediately
-return the retreived value rather than OPAL_BUSY_EVENT.
+Although as of writing all :ref:`OPAL_RTC_READ` backends are asynchronous, there is
+no requirement for them to be - it is valid for :ref:`OPAL_RTC_READ` to immediately
+return the retreived value rather than :ref:`OPAL_BUSY_EVENT`.
 
 **TODO**: describe/document format of arguments.
 
 Return codes
 ------------
 
-OPAL_SUCCESS
+:ref:`OPAL_SUCCESS`
   parameters now contain the current time, or one read from cache.
 
-OPAL_HARDWARE
+:ref:`OPAL_HARDWARE`
   error in retrieving the time. May be transient error,
   may be permanent.
 
-OPAL_PARAMETER
+:ref:`OPAL_PARAMETER`
   year_month_day or hour_minute_second_millisecond parameters are NULL
 
-OPAL_INTERNAL_ERROR
+:ref:`OPAL_INTERNAL_ERROR`
   something went wrong, Possibly reported in error log.
   This can be a transient error
 
-OPAL_BUSY_EVENT
+:ref:`OPAL_BUSY_EVENT`
   request is in flight
 
-OPAL_BUSY
+:ref:`OPAL_BUSY`
   request may be in flight