[PATCH v2 1/2] doc: Document timer API

[Sean Anderson]

This adds kerneldocs for <timer.h>.

I don't know who should maintain doc/api/timer.rst, since the timer
subsystem seems to be maintained by SoC maintainers. MAINTAINERS is left
un-updated for the moment.

Signed-off-by: Sean Anderson <seanga2 at gmail.com>
---

Changes in v2:
- New

 doc/api/index.rst |  1 +
 doc/api/timer.rst |  8 ++++++++
 include/timer.h   | 46 ++++++++++++++++++++++++----------------------
 3 files changed, 33 insertions(+), 22 deletions(-)
 create mode 100644 doc/api/timer.rst

diff --git a/doc/api/index.rst b/doc/api/index.rst
index b7eb5725f2..b8f37f0d86 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -11,4 +11,5 @@ U-Boot API documentation
    linker_lists
    rng
    serial
+   timer
    unicode
diff --git a/doc/api/timer.rst b/doc/api/timer.rst
new file mode 100644
index 0000000000..b0695174d7
--- /dev/null
+++ b/doc/api/timer.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2020 Sean Anderson <seanga2 at gmail.com>
+
+Timer Subsystem
+===============
+
+.. kernel-doc:: include/timer.h
+   :internal:
diff --git a/include/timer.h b/include/timer.h
index 8b9fa51c53..aa9d870619 100644
--- a/include/timer.h
+++ b/include/timer.h
@@ -6,12 +6,12 @@
 #ifndef _TIMER_H_
 #define _TIMER_H_
 
-/*
- * dm_timer_init - initialize a timer for time keeping. On success
+/**
+ * dm_timer_init() - initialize a timer for time keeping. On success
  * initializes gd->timer so that lib/timer can use it for future
  * referrence.
  *
- * @return - 0 on success or error number
+ * Return: 0 on success or error number
  */
 int dm_timer_init(void);
 
@@ -30,49 +30,51 @@ int dm_timer_init(void);
  */
 int timer_timebase_fallback(struct udevice *dev);
 
-/*
- * timer_conv_64 - convert 32-bit counter value to 64-bit
- *
+/**
+ * timer_conv_64() - convert 32-bit counter value to 64-bit
  * @count: 32-bit counter value
- * @return: 64-bit counter value
+ *
+ * Return: 64-bit counter value
  */
 u64 timer_conv_64(u32 count);
 
-/*
- * Get the current timer count
- *
+/**
+ * timer_get_count() - Get the current timer count
  * @dev: The timer device
  * @count: pointer that returns the current timer count
- * @return: 0 if OK, -ve on error
+ *
+ * Return: 0 if OK, -ve on error
  */
 int timer_get_count(struct udevice *dev, u64 *count);
 
-/*
- * Get the timer input clock frequency
- *
+/**
+ * timer_get_rate() - Get the timer input clock frequency
  * @dev: The timer device
- * @return: the timer input clock frequency
+ *
+ * Return: the timer input clock frequency
  */
 unsigned long timer_get_rate(struct udevice *dev);
 
-/*
+/**
  * struct timer_ops - Driver model timer operations
  *
  * The uclass interface is implemented by all timer devices which use
  * driver model.
  */
 struct timer_ops {
-	/*
-	 * Get the current timer count
+	/**
+	 * @get_count: Get the current timer count
 	 *
 	 * @dev: The timer device
+	 *
 	 * @count: pointer that returns the current 64-bit timer count
-	 * @return: 0 if OK, -ve on error
+	 *
+	 * Return: 0 if OK, -ve on error
 	 */
 	int (*get_count)(struct udevice *dev, u64 *count);
 };
 
-/*
+/**
  * struct timer_dev_priv - information about a device used by the uclass
  *
  * @clock_rate: the timer input clock frequency
@@ -84,7 +86,7 @@ struct timer_dev_priv {
 /**
  * timer_early_get_count() - Implement timer_get_count() before driver model
  *
- * If CONFIG_TIMER_EARLY is enabled, this function wil be called to return
+ * If ``CONFIG_TIMER_EARLY`` is enabled, this function wil be called to return
  * the current timer value before the proper driver model timer is ready.
  * It should be implemented by one of the timer values. This is mostly useful
  * for tracing.
@@ -94,7 +96,7 @@ u64 timer_early_get_count(void);
 /**
  * timer_early_get_rate() - Get the timer rate before driver model
  *
- * If CONFIG_TIMER_EARLY is enabled, this function wil be called to return
+ * If ``CONFIG_TIMER_EARLY`` is enabled, this function wil be called to return
  * the current timer rate in Hz before the proper driver model timer is ready.
  * It should be implemented by one of the timer values. This is mostly useful
  * for tracing. This corresponds to the clock_rate value in struct
-- 
2.28.0