ucm: add initial doxygen documenation

This is an attempt to explain the UCM in a more verbose way.

BugLink: https://github.com/alsa-project/alsa-ucm-conf/issues/103
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

1 files changed, 44 insertions, 41 deletions

diff --git a/doc/index.doxygen b/doc/index.doxygen
index cde3b94b..fc2d6596 100644
--- a/doc/index.doxygen
+++ b/doc/index.doxygen
@@ -1,57 +1,60 @@
-/*! \mainpage Index Preamble and License
+/*! \mainpage Index, Preamble and License
 
 \author Jaroslav Kysela <perex@perex.cz>
 \author Abramo Bagnara <abramo@alsa-project.org>
 \author Takashi Iwai <tiwai@suse.de>
 \author Frank van de Pol <fvdpol@coil.demon.nl>
 
-<H2>Preface</H2>
-<P>The Advanced Linux Sound Architecture (\e ALSA) comes with a kernel
+Preface
+-------
+
+The Advanced Linux Sound Architecture (\e ALSA) comes with a kernel
 API and a library API. This document describes the library API and how
-it interfaces with the kernel API.</P>
+it interfaces with the kernel API.
 
-<H2>Documentation License</H2>
+### Documentation License
 
-<P>This documentation is free; you can redistribute it without
-any restrictions. Modifications or derived work must retain
-the copyright and list all authors.</P>
+    This documentation is free; you can redistribute it without
+    any restrictions. Modifications or derived work must retain
+    the copyright and list all authors.
  
-<P>This documentation is distributed in the hope that it will be
-useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</P>
+    This documentation is distributed in the hope that it will be
+    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+API usage
+---------
 
-<H2>API usage</H2>
-<P>Application programmers should use the library API rather than the
+Application programmers should use the library API rather than the
 kernel API. The library offers 100% of the functionality of the kernel API,
 but adds major improvements in usability, making the application code simpler
 and better looking. In addition, future fixes or compatibility code
-may be placed in the library code instead of the kernel driver.</P>
-
-<H2>API links</H2>
-
-<UL>
-  <LI>Page \ref control explains the primitive controls API.
-  <LI>Page \ref control_plugins explains the design of primitive control plugins.
-  <LI>Page \ref hcontrol explains the high-level primitive controls API.
-  <LI>Page \ref mixer explains the mixer controls API.
-  <LI>Page \ref pcm explains the design of the PCM (digital audio) API.
-  <LI>Page \ref pcm_plugins explains the design of PCM (digital audio) plugins.
-  <LI>Page \ref pcm_external_plugins explains the external PCM plugin SDK.
-  <LI>Page \ref ctl_external_plugins explains the external control plugin SDK.
-  <LI>Page \ref rawmidi explains the design of the RawMidi API.
-  <LI>Page \ref timer explains the design of the Timer API.
-  <LI>Page \ref seq explains the design of the Sequencer API.
-  <LI>Page \ref ucm explains the use case API.
-  <LI>Page \ref topology explains the DSP topology API.
-</UL>
-
-<H2>Configuration</H2>
-
-<UL>
-  <LI>Page \ref conf explains the syntax of library configuration files.
-  <LI>Page \ref confarg explains the run-time argument syntax.
-  <LI>Page \ref conffunc explains run-time function definitions and their usage.
-  <LI>Page \ref confhooks explains run-time hook definitions and their usage.
-</UL>
+may be placed in the library code instead of the kernel driver.
+
+API links
+---------
+
+- Page \subpage control explains the primitive controls API.
+- Page \subpage control_plugins explains the design of primitive control plugins.
+- Page \subpage hcontrol explains the high-level primitive controls API.
+- Page \subpage mixer explains the mixer controls API.
+- Page \subpage pcm explains the design of the PCM (digital audio) API.
+- Page \subpage pcm_plugins explains the design of PCM (digital audio) plugins.
+- Page \subpage pcm_external_plugins explains the external PCM plugin SDK.
+- Page \subpage ctl_external_plugins explains the external control plugin SDK.
+- Page \subpage rawmidi explains the design of the RawMidi API.
+- Page \subpage timer explains the design of the Timer API.
+- Page \subpage seq explains the design of the Sequencer API.
+- Page \subpage ucm explains the use case API.
+- Page \subpage topology explains the DSP topology API.
+
+Configuration
+-------------
+
+- Page \subpage conf explains the syntax of library configuration.
+- Page \subpage confarg explains the run-time argument syntax.
+- Page \subpage conffunc explains run-time function definitions and their usage.
+- Page \subpage confhooks explains run-time hook definitions and their usage.
+- Page \subpage ucm_conf explains the UCM configuration and their usage.
 
 */