Doxygen update

doc/Makefile.am

@@ -12,7 +12,7 @@
 #   You should have received a copy of the GNU General Public License
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-EXTRA_DIST = doxygen/Doxyfile.in doxygen/run_doxygen
+EXTRA_DIST = doxygen/Doxyfile.in doxygen/mainpage.md doxygen/run_doxygen
 info_TEXINFOS = libcdio.texi
 libcdio_TEXINFOS = fdl.texi glossary.texi
 

doc/doxygen/mainpage.md

@@ -0,0 +1,50 @@
+# GNU Compact Disc Input and Control Library (`libcdio`) {#mainpage}
+
+Welcome to the API documentation for **libcdio**, the GNU Compact Disc Input and Control Library.
+
+`libcdio` provides a portable, high-level C interface for CD-ROM, CD-DA (Audio CD), Video CD (VCD), and ISO-9660 image access. It abstracts platform-specific OS calls and hardware-level SCSI/MMC commands, allowing applications to inspect disc layouts, extract audio tracks, read ISO filesystem directory trees, and parse CD-TEXT metadata seamlessly across different operating systems.
+
+The specification of SCSI/MMC implemented is the MMC-6 draft 2g from 11 December 2009. It is described in [Working Draft ICITS XXX T10/1836D](https://www.13thmonkey.org/documentation/SCSI/mmc6r02g.pdf).
+
+That draft mentions SCSI Primary Commands, SPC-3. For a draft of SPC-3 that we use, see [dpANS Project T10/1416D](https://www.13thmonkey.org/documentation/SCSI/spc3r23.pdf)
+
+---
+
+## Key Modules & Core API Components
+
+The library is modularized into several core subsystems:
+
+* **[CD-ROM & Drive Control](@ref cdio_cdio)** (`cdio/cdio.h`): Primary interfaces for drive detection, device opening, track/sector reading, and hardware control.
+* **[CD-TEXT Handling](@ref cdio_cdtext)** (`cdio/cdtext.h`): Data structures and conversion utilities for parsing CD-TEXT field descriptors, language codes, and track metadata.
+* **[ISO-9660 Filesystem](@ref cdio_iso9660)** (`cdio/iso9660.h`): Parsing ISO-9660 images, directory traversal, volume descriptors, and file extraction.
+* **[MMC Subsystem](@ref cdio_mmc)** (`cdio/mmc.h`): Low-level SCSI Multimedia Commands (MMC) interface for direct drive feature querying and command execution.
+* **[Audio & Device Utilities](@ref cdio_audio)** (`cdio/audio.h`, `cdio/sector.h`): Sector address conversions (LSN/LBA/MSF) and audio playback controls.
+
+---
+
+## Quick Start Example
+
+Here is a basic example opening a default CD-ROM device and querying track details:
+
+@code{.c}
+#include <stdio.h>
+#include <cdio/cdio.h>
+#include <cdio/logging.h>
+
+int main(void) {
+    CdIo_t *p_cdio = cdio_open(NULL, DRIVER_UNKNOWN);
+    if (!p_cdio) {
+        fprintf(stderr, "No CD-ROM drive found or failed to open.\n");
+        return 1;
+    }
+
+    track_t i_tracks = cdio_get_num_tracks(p_cdio);
+    track_t i_first  = cdio_get_first_track_num(p_cdio);
+
+    printf("Drive opened successfully. Total tracks: %d (First track: %d)\n",
+           i_tracks, i_first);
+
+    cdio_destroy(p_cdio);
+    return 0;
+}
+@endcode

include/cdio/audio.h

@@ -1,5 +1,5 @@
 /* -*- c -*-
-    Copyright (C) 2005, 2007, 2008, 2019 Rocky Bernstein <[email protected]>
+    Copyright (C) 2005, 2007, 2008, 2019, 2026 Rocky Bernstein <[email protected]>
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -15,9 +15,9 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-/** \file audio.h
+/** @file audio.h
  *
- *  \brief The top-level header for CD audio-related libcdio
+ *  @brief The top-level header for CD audio-related libcdio
  *         calls.  These control playing of the CD-ROM through its
  *         line-out jack.
  */
@@ -30,114 +30,112 @@
 extern "C" {
 #endif /* __cplusplus */
 
-  /** This struct is used by the cdio_audio_read_subchannel */
-  typedef struct cdio_subchannel_s
-  {
-    uint8_t format;
-    uint8_t audio_status;
-    uint8_t address:	4;
-    uint8_t control:	4;
-    uint8_t track;
-    uint8_t index;
-    msf_t   abs_addr;
-    msf_t   rel_addr;
-  } cdio_subchannel_t;
-
-  /** This struct is used by cdio_audio_get_volume and cdio_audio_set_volume */
-  typedef struct cdio_audio_volume_s
-  {
-    uint8_t level[4];
-  } cdio_audio_volume_t;
-
-
-  /** This struct is used by the CDROMPLAYTRKIND ioctl */
-  typedef struct cdio_track_index_s
-  {
-    uint8_t	i_start_track;	/**< start track */
-    uint8_t	i_start_index;	/**< start index */
-    uint8_t	i_end_track;	/**< end track */
-    uint8_t	i_end_index;	/**< end index */
-  } cdio_track_index_t;
-
-  /**
-    Get volume of an audio CD.
-
-    @param p_cdio the CD object to be acted upon.
-    @param p_volume place to put the list of volume outputs levels
-
-    \p p_volume can be \p NULL in which case we return only whether
-    the driver has the ability to get the volume or not.
-
-  */
-  driver_return_code_t cdio_audio_get_volume (CdIo_t *p_cdio,  /*out*/
-					      cdio_audio_volume_t *p_volume);
-
-  /**
-    Return the number of seconds (discarding frame portion) of an MSF
-  */
-  uint32_t cdio_audio_get_msf_seconds(msf_t *p_msf);
-
-  /**
-    Pause playing CD through analog output
-
-    @param p_cdio the CD object to be acted upon.
-  */
-  driver_return_code_t cdio_audio_pause (CdIo_t *p_cdio);
-
-  /**
-    Playing CD through analog output at the given MSF.
-
-    @param p_cdio the CD object to be acted upon.
-    @param p_start_msf pointer to staring MSF
-    @param p_end_msf pointer to ending MSF
-  */
-  driver_return_code_t cdio_audio_play_msf (CdIo_t *p_cdio,
-					    /*in*/msf_t *p_start_msf,
-					    /*in*/ msf_t *p_end_msf);
-
-  /**
-    Playing CD through analog output at the desired track and index
-
-    @param p_cdio the CD object to be acted upon.
-    @param p_track_index location to start/end.
-  */
-  driver_return_code_t cdio_audio_play_track_index
-  ( CdIo_t *p_cdio,  cdio_track_index_t *p_track_index);
-
-  /**
-    Get subchannel information.
-
-    @param p_cdio the CD object to be acted upon.
-    @param p_subchannel place for returned subchannel information
-  */
-  driver_return_code_t cdio_audio_read_subchannel (CdIo_t *p_cdio,
-						   /*out*/ cdio_subchannel_t *p_subchannel);
-
-  /**
-    Resume playing an audio CD.
-
-    @param p_cdio the CD object to be acted upon.
-
-  */
-  driver_return_code_t cdio_audio_resume (CdIo_t *p_cdio);
-
-  /**
-    Set volume of an audio CD.
-
-    @param p_cdio the CD object to be acted upon.
-    @param p_volume place for returned volume-level information
-
-  */
-  driver_return_code_t cdio_audio_set_volume (CdIo_t *p_cdio, /*out*/
-					      cdio_audio_volume_t *p_volume);
-
-  /**
-    Stop playing an audio CD.
-
-    @param p_cdio the CD object to be acted upon.
+/** This struct is used by the cdio_audio_read_subchannel() */
+typedef struct cdio_subchannel_s {
+  uint8_t format;
+  uint8_t audio_status;
+  uint8_t address : 4;
+  uint8_t control : 4;
+  uint8_t track;
+  uint8_t index;
+  msf_t abs_addr;
+  msf_t rel_addr;
+} cdio_subchannel_t;
+
+/** This struct is used by cdio_audio_get_volume() and cdio_audio_set_volume()
+ */
+typedef struct cdio_audio_volume_s {
+  uint8_t level[4];
+} cdio_audio_volume_t;
+
+/** This struct is used by the `CDROMPLAYTRKIND` ioctl */
+typedef struct cdio_track_index_s {
+  uint8_t i_start_track; /**< start track */
+  uint8_t i_start_index; /**< start index */
+  uint8_t i_end_track;   /**< end track */
+  uint8_t i_end_index;   /**< end index */
+} cdio_track_index_t;
+
+/**
+  Get the volume of an audio CD.
+
+  @param p_cdio the CD object to be acted upon.
+  @param p_volume place to put the list of volume output levels
+
+  @p p_volume can be `NULL`, in which case we return only whether
+  the driver has the ability to get the volume or not.
+
+*/
+driver_return_code_t cdio_audio_get_volume(CdIo_t *p_cdio, /*out*/
+                                           cdio_audio_volume_t *p_volume);
+
+/**
+  Return the number of seconds (discarding frame portion) of an MSF
+*/
+uint32_t cdio_audio_get_msf_seconds(msf_t *p_msf);
+
+/**
+  Pause playing CD through analog output
+
+  @param p_cdio the CD object to be acted upon.
+*/
+driver_return_code_t cdio_audio_pause(CdIo_t *p_cdio);
+
+/**
+  Playing CD through analog output at the given MSF.
+
+  @param p_cdio the CD object to be acted upon.
+  @param p_start_msf pointer to staring MSF
+  @param p_end_msf pointer to ending MSF
+*/
+driver_return_code_t cdio_audio_play_msf(CdIo_t *p_cdio,
+                                         /*in*/ msf_t *p_start_msf,
+                                         /*in*/ msf_t *p_end_msf);
+
+/**
+  Playing CD through analog output at the desired track and index
 
-  */
-  driver_return_code_t cdio_audio_stop (CdIo_t *p_cdio);
+  @param p_cdio the CD object to be acted upon.
+  @param p_track_index location to start/end.
+*/
+driver_return_code_t
+cdio_audio_play_track_index(CdIo_t *p_cdio, cdio_track_index_t *p_track_index);
+
+/**
+  Get subchannel information.
+
+  @param p_cdio the CD object to be acted upon.
+  @param p_subchannel place for returned subchannel information
+*/
+driver_return_code_t
+cdio_audio_read_subchannel(CdIo_t *p_cdio,
+                           /*out*/ cdio_subchannel_t *p_subchannel);
+
+/**
+  Resume playing an audio CD.
+
+  @param p_cdio the CD object to be acted upon.
+
+*/
+driver_return_code_t cdio_audio_resume(CdIo_t *p_cdio);
+
+/**
+  Set the volume of an audio CD.
+
+  @param p_cdio the CD object to be acted upon.
+  @param p_volume place for returned volume-level information
+
+*/
+driver_return_code_t cdio_audio_set_volume(CdIo_t *p_cdio, /*out*/
+                                           cdio_audio_volume_t *p_volume);
+
+/**
+  Stop playing an audio CD.
+
+  @param p_cdio the CD object to be acted upon.
+
+*/
+driver_return_code_t cdio_audio_stop(CdIo_t *p_cdio);
 
 #ifdef __cplusplus
 }