# HG changeset patch
# User richwareham
# Date 1023375789 0
# Node ID 0ba15bf3dc25063c725181a03b30a6ca13df7cfb
# Parent  131ad65a2398806f6867283d2c823274193cb757
Biiiiiiig change to let doxygen generate some docs for the library. Note that I'm in no way sure that the autoconf stuff plays nice.

diff -r 131ad65a2398 -r 0ba15bf3dc25 dvd_types.h
--- a/dvd_types.h	Tue Jun 04 13:35:16 2002 +0000
+++ b/dvd_types.h	Thu Jun 06 15:03:09 2002 +0000
@@ -28,6 +28,12 @@
 #include <inttypes.h>
 
 /**
+ * \file dvd_types.h
+ *
+ * Various useful structs and enums for DVDs.
+ */
+
+/**
  * DVD Domain
  */
 typedef enum {
@@ -279,12 +285,15 @@
   int more_to_come;
 } DVDVideoAttributes_t;
 
+/**
+ * Atructure containing info on highlight areas.
+ */
 typedef struct {
-  uint32_t palette;  /* The CLUT entries for the highlight palette
+  uint32_t palette;  /*!< The CLUT entries for the highlight palette
                         (4-bits per entry -> 4 entries) */
-  uint16_t sx,sy,ex,ey; /* The start/end x,y positions */
-  uint32_t pts;         /* Highlight PTS to match with SPU */
-  uint32_t buttonN;     /* Button number for the SPU decoder. */
+  uint16_t sx,sy,ex,ey; /*!< The start/end x,y positions */
+  uint32_t pts;         /*!< Highlight PTS to match with SPU */
+  uint32_t buttonN;     /*!< Button number for the SPU decoder. */
 } dvdnav_highlight_area_t;
 
 
diff -r 131ad65a2398 -r 0ba15bf3dc25 dvdnav.c
--- a/dvdnav.c	Tue Jun 04 13:35:16 2002 +0000
+++ b/dvdnav.c	Thu Jun 06 15:03:09 2002 +0000
@@ -411,7 +411,7 @@
   vobu->vobu_start = nav_dsi->dsi_gi.nv_pck_lbn; /* Absolute offset from start of disk */
   vobu->vobu_length = nav_dsi->dsi_gi.vobu_ea; /* Relative offset from vobu_start */
      
-  /**
+  /*
    * If we're not at the end of this cell, we can determine the next
    * VOBU to display using the VOBU_SRI information section of the
    * DSI.  Using this value correctly follows the current angle,
@@ -931,6 +931,9 @@
 
 /*
  * $Log$
+ * Revision 1.21  2002/06/06 15:03:09  richwareham
+ * Biiiiiiig change to let doxygen generate some docs for the library. Note that I'm in no way sure that the autoconf stuff plays nice.
+ *
  * Revision 1.20  2002/06/04 13:35:16  richwareham
  * Removed more C++ style comments
  *
diff -r 131ad65a2398 -r 0ba15bf3dc25 dvdnav.h
--- a/dvdnav.h	Tue Jun 04 13:35:16 2002 +0000
+++ b/dvdnav.h	Thu Jun 06 15:03:09 2002 +0000
@@ -21,6 +21,12 @@
  *
  */
 
+/**
+ * \file dvdnav.h
+ * The main file you should include if you want to access dvdnav
+ * functionality.
+ */
+
 #ifndef DVDNAV_H_INCLUDED
 #define DVDNAV_H_INCLUDED
 
@@ -36,7 +42,11 @@
 
 #include <dvdread/dvd_reader.h>
 
-/* Opaque dvdnav data-type */
+/**
+ * Opaque data-type can be viewed as a 'DVD handle'. You should get
+ * a pointer to a dvdnav_t from the dvdnav_open() function.
+ * \sa dvdnav_open()
+ */
 typedef struct dvdnav_s dvdnav_t;
 
 /* Status */
@@ -46,20 +56,32 @@
 #define DVDNAV_STATUS_OK  1
 
 /**
- * NOTE: Unless otherwise stated, all functions return DVDNAV_STATUS_OK if
+ * NOTE: */
+
+/** 
+ * \defgroup init Initialisation & housekeeping functions 
+ * These functions allow you to open a DVD device and associate it
+ * with a dvdnav_t.
+ * 
+ *  Unless otherwise stated, all functions return DVDNAV_STATUS_OK if
  * they succeeded, otherwise DVDNAV_STATUS_ERR is returned and the error may
  * be obtained by calling dvdnav_err_to_string().
+ *
+ * A minimal <tt>libdvdnav</tt> program should always call dvdnav_open()
+ * and dvdnav_close().
+ *
+ * \par Example:
+ * \include minimal.c
+ * 
+ * @{
  */
 
-/*** Initialisation & housekeeping functions ***/
-
 /**
  * Attempts to open the DVD drive at the specifiec path and pre-cache
  * any CSS-keys that your hacked libdvdread may use.
  *
- * Arguments:
- *   dest     -- Pointer to a dvdnav_t pointer to fill in.
- *   path     -- Any libdvdread acceptable path
+ * \param dest Pointer to a dvdnav_t pointer to fill in.
+ * \param path Any libdvdread acceptable path
  */
 dvdnav_status_t dvdnav_open(dvdnav_t** dest, char *path); 
 
@@ -67,70 +89,107 @@
  * Closes a dvdnav_t previously opened with dvdnav_open(), freeing any 
  * memory associated with it.
  *
- * Arguments:
- *   self     -- dvdnav_t to close.
+ * \param self dvdnav_t to close.
  */
 dvdnav_status_t dvdnav_close(dvdnav_t *self);
 
 /**
- * Resets the VM and buffers in a previously opened dvdnav
+ * Resets the virtual machine and buffers in a previously opened dvdnav
  *
- * Arguments:
- *   self     -- dvdnav_t to reset.
+ * \param self dvdnav_t to reset.
  */
 dvdnav_status_t dvdnav_reset(dvdnav_t *self);
 
 /**
- * Fills a pointer wiht a value pointing to a string describing
+ * Fills a pointer with a value pointing to a string describing
  * the path associated with an open dvdnav_t. It assigns it NULL
  * on error.
  *
- * Arguments:
- *   path     -- Pointer to char* to fill in.
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param path Pointer to char* to fill in.
  */
 dvdnav_status_t dvdnav_path(dvdnav_t *self, char** path);
 
 /**
  * Returns a human-readable string describing the last error.
  *
- * Returns: A pointer to said string.
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \returns A pointer to said string.
  */
 char* dvdnav_err_to_string(dvdnav_t *self);
 
-/** DVD Player characteristics (FIXME: Need more entries) **/
+/** \@} */
+
+/** 
+ * \defgroup char Changing and Reading DVD Player characteristics
+ * 
+ * These functions allow you to manipulate the various global characteristics
+ * of the DVD playback engine.
+ * 
+ * @{
+ */
 
 /**
- * Returns the region mask (bit 0 - region 1, bit 1 - R 2, etc) of the
- * VM
+ * Returns the region mask (bit 0 set implies region 1, bit 1 set implies
+ * region 2, etc) of the virtual machine. Generally you will only need to set
+ * this if you are playing RCE discs which query the virtual machine as to its
+ * region setting. 
+ *
+ * \par Note:
+ * This has <b>nothing</b> to do with the region setting of the DVD drive.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param region Pointer to an int which will receive the region code mask.
  */
 dvdnav_status_t dvdnav_get_region_mask(dvdnav_t *self, int *region);
 
 /**
- * Sets the region mask of the VM.
+ * Sets the region mask of the virtual machine.
  *
- * mask: 0x00..0xff
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param mask 0x00..0xff -- the desired region mask.
+ *
+ * \sa dvdnav_get_region_mask()
  */
 dvdnav_status_t dvdnav_set_region_mask(dvdnav_t *self, int mask);
 
 /**
- * Specify whether read-ahead caching should be used 
+ * Specify whether read-ahead caching should be used. You may not want this if your
+ * decoding engine does its own buffering or if you don't like the fact that this is
+ * implemented in a multithreaded manner.
  * 
- * use_readahead: 0 - no, 1 - yes
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param use_readahead 0 - no, 1 - yes
  */
 dvdnav_status_t dvdnav_set_readahead_flag(dvdnav_t *self, int use_readahead);
 
 /**
- * Query state of readahead flag
+ * Query whether readahead caching/buffering will be used.
  *
- * flag: pointer to int to recieve flag value
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param flag Pointer to int to recieve flag value.
+ *
+ * \sa dvdnav_get_readahead_flag()
  */
 dvdnav_status_t dvdnav_get_readahead_flag(dvdnav_t *self, int* flag);
 
-/** Getting data **/
+/**
+ * @}
+ */
 
 /**
- * Gets the next block off the DVD places it in 'buf'. If there is any
- * special information, the value pointed to by 'event' gets set 
+ * \defgroup data Reading Data
+ *
+ * These functions are used to poll the playback enginge and actually get data 
+ * off the DVD.
+ *
+ * @{
+ */
+
+/**
+ * Attempts to get the next block off the DVD and copies it into the buffer 'buf'. 
+ * If there is any special actions that may need to be performed, the value
+ * pointed to by 'event' gets set 
  * accordingly.
  *
  * If 'event' is DVDNAV_BLOCK_OK then 'buf' is filled with the next block
@@ -138,43 +197,75 @@
  * then set to 2048.
  *
  * Otherwise, buf is filled with an appropriate event structure and
- * len is set to the length of that structure,
+ * len is set to the length of that structure.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param buf Buffer (at least 2048 octets) to fill with next block/event structure.
+ * \param event Pointer to int to get event type.
+ * \param len Pointer to int to get the number of octets written into buf.
  */
 dvdnav_status_t dvdnav_get_next_block(dvdnav_t *self, unsigned char *buf,
 				      int *event, int *len);
 
-/** Navigation **/
+/**
+ * Get video aspect code.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * 
+ * \returns Video aspect ratio code, 0 -- 4:3, 2 -- 16:9
+ */
+uint8_t dvdnav_get_video_aspect(dvdnav_t *self);
 
 /**
- * Returns the number of titles on the disk in titles.
+ * @}
+ */
+
+/**
+ * \defgroup nav Navigation Commands
+ *
+ * @{
+ */
+
+/**
+ * Returns the number of titles on the disk.
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param titles Pointer to int to receive number of titles.
  */
 dvdnav_status_t dvdnav_get_number_of_titles(dvdnav_t *self, int *titles);
 
 /**
- * Returns the number of programs within the current title in programs.
+ * Returns the number of programs within the current title.
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param programs Pointer to int to receive number of programs.
  */
 dvdnav_status_t dvdnav_get_number_of_programs(dvdnav_t *self, int *programs);
 
 /**
- * If we are currently in a still-frame, skip it.
+ * If we are currently in a still-frame this function skips it (or attempts to).
+ * This might fail if this still-frame is of infinite duration as most DVD
+ * authors wouldn't expect you to be able to do this <tt>:)</tt>
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
  */
 dvdnav_status_t dvdnav_still_skip(dvdnav_t *self);
 
 /**
- * Plays a specified title of the DVD 
+ * Plays a specified title of the DVD.
  *
- * Arguments:
- *   title  -- 1..99
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param title 1..99 -- Title number to play.
  */
 dvdnav_status_t dvdnav_title_play(dvdnav_t *self, int title);
 
 /**
  * Plays the specifiec title, starting from the specified
- * part (chapter)
+ * part (chapter).
  *
- * Arguments:
- *   title  -- 1..99
- *   part   -- 1..999
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param title 1..99 -- Title number to play.
+ * \param part 1..999 -- Part to start from.
  */
 dvdnav_status_t dvdnav_part_play(dvdnav_t *self, int title, int part);
 
@@ -182,10 +273,13 @@
  * Play the specified amount of parts of the specified title of
  * the DVD then STOP.
  *
- * Arguments:
- *   title  -- 1..99
- *   part   -- 1..999
- *   parts_to_play -- 1..999
+ * \par Note:
+ * Currently unimplemented!
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param title 1..99 -- Title number to play.
+ * \param part 1..999 -- Part to start from.
+ * \param parts_to_play 1..999 -- Number of parts to play.
  */
 dvdnav_status_t dvdnav_part_play_auto_stop(dvdnav_t *self, int title,
 					  int part, int parts_to_play);
@@ -193,32 +287,53 @@
 /**
  * Play the specified title starting from the specified time
  *
- * Arguments:
- *   title -- 1..99
- *   time: (timecode) hours, minutes, seconds + frames.
+ * \par Note:
+ * Currently unimplemented!
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param title 1..99 -- Title number to play.
+ * \param time Timecode to start from (hours, minutes, seconds + frames).
  */
 dvdnav_status_t dvdnav_time_play(dvdnav_t *self, int title,
 				unsigned long int time);
 
 /**
  * Stops playing the current title (causes a STOP action in
- * dvdnav_get_next_block).
+ * dvdnav_get_next_block()).
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ *
+ * \sa dvdnav_get_next_block()
  */
 dvdnav_status_t dvdnav_stop(dvdnav_t *self);
 
 /**
- * Stop playing current title and play the "GoUp"-program chain  
+ * Stop playing current title and play the "GoUp"-program chain 
+ * (which generally leads to the title menu or a higer-level menu).
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
  */
 dvdnav_status_t dvdnav_go_up(dvdnav_t *self);
 
-/** SEARCHING **/
+/**
+ * @}
+ */
+
+/** 
+ * \defgroup search Searching
+ *
+ * @{
+ */
 
 /**
  * Stop playing the current title and start playback of the title
  * from the specified timecode.
  *
- * Arguments:
- *   time -- timecode.
+ * \par Note:
+ * Currently unimplemented!
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param time Timecode to start from.
  */
 dvdnav_status_t dvdnav_time_search(dvdnav_t *self, 
 				  unsigned long int time);
@@ -227,9 +342,9 @@
  * Stop playing the current title and start playback of the title
  * from the specified sector offset.
  *
- * Arguments:
- *   offset -- sector offset.
- *   origin -- Start from here, start or end.
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param offset Sector offset to start from.
+ * \param origin Start from here, start or end.
  */
 dvdnav_status_t dvdnav_sector_search(dvdnav_t *self, 
 				  unsigned long int offset, int origin);
@@ -238,52 +353,74 @@
  * Stop playing the current title and start playback of the title
  * from the specified part (chapter).
  *
- * Arguments:
- *   part: 1..999
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param part 1..999 -- Part to start from.
  */
 dvdnav_status_t dvdnav_part_search(dvdnav_t *self, int part);
 
 /**
  * Stop playing the current title and start playback of the title
- * from the previous program (if it exists)
+ * from the previous program (if it exists).
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
  */
 dvdnav_status_t dvdnav_prev_pg_search(dvdnav_t *self);
 
 /**
  * Stop playing the current title and start playback of the title
  * from the first program.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
  */
 dvdnav_status_t dvdnav_top_pg_search(dvdnav_t *self);
 
 /**
  * Stop playing the current title and start playback of the title
- * from the next program (if it exists)
+ * from the next program (if it exists).
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
  */
 dvdnav_status_t dvdnav_next_pg_search(dvdnav_t *self);
 
 /**
  * Stop playing the current title and jump to the specified menu.
  *
- * Arguments:
- *   menu -- Which menu to call
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param menu Which menu to call (see DVDMenuID_t).
+ *
+ * \sa DVDMenuID_t (from <tt>libdvdread</tt>)
  */
 dvdnav_status_t dvdnav_menu_call(dvdnav_t *self, DVDMenuID_t menu);
 
 /**
  * Return the title number and chapter currently being played or
  * -1 if in a menu.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param title Pointer to into which will receive the current title number.
+ * \param part Pointer to into which will receive the current part number.
  */
 dvdnav_status_t dvdnav_current_title_info(dvdnav_t *self, int *title,
 			     		  int *part);
 
 /**
- * Return a string describing the title
+ * Return a string describing the title. This is an ID string encoded on the
+ * disc byt the author. In many cases this is a descriptive string such as
+ * `<tt>THE_MATRIX</tt>' but sometimes is sigularly uninformative such as
+ * `<tt>PDVD-011421</tt>'.
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param title_str Pointer to C-style string to receive a string describing the title. 
  */
 dvdnav_status_t dvdnav_get_title_string(dvdnav_t *self, char **title_str);
 
 /**
  * Return the current position (in blocks) within the current
  * part and the length (in blocks) of said part.
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param pos Pointer to unsigned int to get the current position.
+ * \param len Pointer to unsinged int to hold the length of the current part.
  */
 dvdnav_status_t dvdnav_get_position(dvdnav_t *self, unsigned int* pos,
 				    unsigned int *len);
@@ -291,84 +428,166 @@
 /**
  * Return the current position (in blocks) within the current
  * title and the length (in blocks) of said title.
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param pos Pointer to unsigned int to get the current position.
+ * \param len Pointer to unsinged int to hold the length of the current title.
  */
 dvdnav_status_t dvdnav_get_position_in_title(dvdnav_t *self,
 					     unsigned int* pos,
 					     unsigned int *len);
 
-/** Highlights **/
+/**
+ * @}
+ */
 
 /**
- * Set the value pointed to to the currently highlighted button 
+ * \defgroup highlight Highlights
+ *
+ * @{
+ */
+
+/**
+ * Get the currently highlighted button 
  * number (1..36) or 0 if no button is highlighed.
  *
- * Arguments:
- *   button -- Pointer to the value to fill in.
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param button Pointer to the value to fill in.
  */
 dvdnav_status_t dvdnav_get_current_highlight(dvdnav_t *self, int* button);
+
+/**
+ * Returns the Presentation Control Information (PCI) structure associated
+ * with the current position.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ *
+ * \sa pci_t (in <tt>libdvdread</tt>)
+ */
 pci_t* dvdnav_get_current_nav_pci(dvdnav_t *self);
+
+/**
+ * Get the area associated with a certain button.
+ *
+ * \param nav_pci Pointer to the PCI structure you may have got via
+ * dvdnav_get_current_nav_pci().
+ *
+ * \param button Button number to query.
+ * \param mode 0..3 -- Button mode to query.
+ * \param highlight Pointer to dvdnav_highlight_area_t to fill in.
+ *
+ * \sa dvdnav_highlight_area_t
+ */
 dvdnav_status_t dvdnav_get_highlight_area(pci_t* nav_pci , int32_t button, int32_t mode,
                                            dvdnav_highlight_area_t* highlight);
 
 /**
- * Move button highlight around (e.g. with arrow keys)
+ * Move button highlight around as suggested by function name (e.g. with arrow keys).
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
  */
 dvdnav_status_t dvdnav_upper_button_select(dvdnav_t *self);
+/**
+ * Move button highlight around as suggested by function name (e.g. with arrow keys).
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ */
 dvdnav_status_t dvdnav_lower_button_select(dvdnav_t *self);
+/**
+ * Move button highlight around as suggested by function name (e.g. with arrow keys).
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ */
 dvdnav_status_t dvdnav_right_button_select(dvdnav_t *self);
+/**
+ * Move button highlight around as suggested by function name (e.g. with arrow keys).
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ */
 dvdnav_status_t dvdnav_left_button_select(dvdnav_t *self);
 
 /**
- * Activate (press) highlighted button
+ * Activate (press) the currently highlighted button.
+ * \param self Pointer to dvdnav_t associated with this operation.
  */
 dvdnav_status_t dvdnav_button_activate(dvdnav_t *self);
 
 /**
- * Highlight a specific button button
+ * Highlight a specific button.
  *
- * button -- 1..39.
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param button 1..39 -- Button number to activate.
  */
 dvdnav_status_t dvdnav_button_select(dvdnav_t *self, int button);
 
 /**
  * Activate (press) specified button.
  *
- * Arguments:
- *   button: 1..36
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param button 1..39 -- Button number to activate.
  */
 dvdnav_status_t dvdnav_button_select_and_activate(dvdnav_t *self, int button);
 
 /**
  * Select button at specified (image) co-ordinates.
  *
- * Arguments:
- *   x,y: Image co-ordinates
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param x X co-ordinate in image.
+ * \param y Y xo-ordinate in image.
  */
 dvdnav_status_t dvdnav_mouse_select(dvdnav_t *self, int x, int y);
 
 /**
  * Activate (press) button at specified co-ordinates.
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param x X co-ordinate in image.
+ * \param y Y xo-ordinate in image.
  */
 dvdnav_status_t dvdnav_mouse_activate(dvdnav_t *self, int x, int y);
 
-/** i18n **/
+/**
+ * @}
+ */
+
+/** 
+ * \defgroup languages Menu Languages
+ *
+ * @{
+ */
 
 /**
- * Set specified menu language.
+ * Set which menu language we should use.
  *
- * Arguments:
- *   code: 1 char ISO 639 Language code 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param code 2 char ISO639 Language code in a C-style string.
  */
 dvdnav_status_t dvdnav_menu_languge_select(dvdnav_t *self,
 					  char *code);
 
-/** SPU/Audio streams **/
+/**
+ * @}
+ */
+
+/** 
+ * \defgroup streams Sub-Picture Unit (Subtitles) and Audio Streams 
+ *
+ * All these commands manipulate the audio/subtitle stream numbers that the
+ * player engine thinks is playing. Note that all the streams are still returned
+ * multiplexed by dvdnav_get_next_block(). You should try to make sure that the
+ * MPEG demuxer and the player engine both have the same thoughts on what stream the
+ * user is currently listening to.
+ *
+ * \sa dvdnav_get_next_block()
+ * 
+ * @{
+ */
 
 /**
  * Set a specific PHYSICAL MPEG stream.
  *
- * Arguments:
- *   audio: 0..7
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param audio 0..7 -- Stream number.
  */
 dvdnav_status_t dvdnav_physical_audio_stream_change(dvdnav_t *self,
 						   int audio);
@@ -376,8 +595,8 @@
 /**
  * Set a specific logical audio stream.
  *
- * Arguments:
- *   audio: 0..7
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param audio 0..7 -- Stream number.
  */
 dvdnav_status_t dvdnav_logical_audio_stream_change(dvdnav_t *self,
 		       				  int audio);
@@ -386,8 +605,8 @@
  * Set the int pointed to to the current PHYSICAL audio
  * stream.
  *
- * Arguments:
- *   audio: Pointer to value
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param audio Pointer to int which will receive value.
  */
 dvdnav_status_t dvdnav_get_physical_audio_stream(dvdnav_t *self, int* audio);
 
@@ -395,8 +614,8 @@
  * Set the int pointed to to the current LOGICAL audio
  * stream.
  *
- * Arguments:
- *   audio: Pointer to value
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param audio Pointer to int which will receive value.
  */
 dvdnav_status_t dvdnav_get_logical_audio_stream(dvdnav_t *self, int* audio);
 
@@ -404,9 +623,9 @@
  * Set a specific PHYSICAL MPEG SPU stream and whether it should be
  * displayed.
  *
- * Arguments:
- *   stream: 0..31 or 63 (dummy)
- *   display: 0..1
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param stream 0..31 or 63 (dummy) -- Stram number.
+ * \param display: 0..1 -- Is this actually being displayed?
  */
 dvdnav_status_t dvdnav_physical_spu_stream_change(dvdnav_t *self,
 					  	  int stream, int display);
@@ -415,9 +634,9 @@
  * Set a specific LOGICAL SPU stream and whether it should be
  * displayed.
  *
- * Arguments:
- *   stream: 0..31 or 63 (dummy)
- *   display: 0..1
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param stream 0..31 or 63 (dummy) -- Stram number.
+ * \param display: 0..1 -- Is this actually being displayed?
  */
 dvdnav_status_t dvdnav_logical_spu_stream_change(dvdnav_t *self,
 						 int stream, int display);
@@ -426,77 +645,206 @@
  * Set the ints pointed to to the current PHYSICAL SPU
  * stream & display flag.
  *
- * Arguments:
- *   stream, display: Pointers to value
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param stream Pointer which will receive value.
+ * \param display Pointer which will receive value.
  */
 dvdnav_status_t dvdnav_get_physical_spu_stream(dvdnav_t *self,
-					       int* stream, int* disply);
+					       int* stream, int* display);
 
 /**
  * Set the ints pointed to to the current LOGICAL SPU
  * stream & display flag.
  *
- * Arguments:
- *   stream, display: Pointers to value
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param stream Pointer which will receive value.
+ * \param display Pointer which will receive value.
  */
 dvdnav_status_t dvdnav_get_logical_spu_stream(dvdnav_t *self,
 		       			     int* stream, int* disply);
 
-/** ANGLES **/
+/**
+ * Converts a *logical* audio stream id into country code 
+ * (returns <tt>0xffff</tt> if no such stream).
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param stream Stream number
+ */
+uint16_t dvdnav_audio_stream_to_lang(dvdnav_t *self, uint8_t stream);
+
+/**
+ * Converts a *logical* subpicture stream id into country code 
+ * (returns <tt>0xffff</tt> if no such stream).
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param stream Stream number
+ */
+uint16_t dvdnav_spu_stream_to_lang(dvdnav_t *self, uint8_t stream);
+
+/**
+ * Converts a *physical* audio stream id into a logical stream number 
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param audio_num Stream number
+ */
+int8_t dvdnav_get_audio_logical_stream(dvdnav_t *self, uint8_t audio_num);
 
 /**
- * Sets the current angle 
+ * Converts a *physical* subpicture stream id into a logical stream number 
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param subp_num Stream number
+ */
+int8_t dvdnav_get_spu_logical_stream(dvdnav_t *self, uint8_t subp_num);
+
+/**
+ * Get active spu stream.
+ * 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ */
+int8_t dvdnav_get_active_spu_stream(dvdnav_t *self);
+
+/**
+ * @}
+ */
+
+/** 
+ * \defgroup angles Multiple angles
  *
- * Arguments:
- *   angle: 1..9
+ * The <tt>libdvdnav</tt> library abstracts away the difference between seamless and
+ * non-seamless angles. From the point of view of the programmer you just set the
+ * angle number and all is well in the world. 
+ *
+ * \par Note:
+ * It is quite possible that some tremendously strange DVD feature might change the
+ * angle number from under you. Generally you should always view the results from
+ * dvdnav_get_angle_info() as definitive only up to the next time you call
+ * dvdnav_get_next_block().
+ *
+ * @{
+ */
+
+/**
+ * Sets the current angle. If you try to follow a non existant angle
+ * the call fails.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param angle 1..9 -- Currentl angle to follow.
  */
 dvdnav_status_t dvdnav_angle_change(dvdnav_t *self, int angle);
 
 /**
- * Returns the current angle and number of angles present
+ * Returns the current angle and number of angles present.
+ *
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \param current_angle Pointer to int which will get the current angle.
+ * \param number_of_angles Pointer to int which will get the number of angles.
  */
 dvdnav_status_t dvdnav_get_angle_info(dvdnav_t *self, int* current_angle,
 				     int *number_of_angles);
 
+/**
+ * FIXME: WTF does this do? -- High qulaity documentation huh?
+ */
 dvdnav_status_t dvdnav_get_cell_info(dvdnav_t *self, int* current_angle,
 				     int *number_of_angles);
+
 /**
- * Converts a *logical* subpicture stream id into country code 
- * (returns 0xffff if no such stream).
+ * @}
  */
-uint16_t dvdnav_audio_stream_to_lang(dvdnav_t *self, uint8_t stream);
-uint16_t dvdnav_spu_stream_to_lang(dvdnav_t *self, uint8_t stream);
+
+/** 
+ * \defgroup domain Domain Queries
+ *
+ * The following functions can be used to query whether we are in
+ * particular domains or not.
+ *
+ * @{
+ */
 
 /**
- * Get substream id for logical stream *_num.
+ * Are we in the First Play domain. (Menu) 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \returns -1 on failure, 1 if condition is true, 0 if condition is false
+ */
+int8_t dvdnav_is_domain_fp(dvdnav_t *self);
+/**
+ * Are we in the Video management Menu domain. (Menu) 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \returns -1 on failure, 1 if condition is true, 0 if condition is false
  */
-int8_t dvdnav_get_audio_logical_stream(dvdnav_t *self, uint8_t audio_num);
-int8_t dvdnav_get_spu_logical_stream(dvdnav_t *self, uint8_t subp_num);
+int8_t dvdnav_is_domain_vmgm(dvdnav_t *self);
+/**
+ * Are we in the Video Title Menu domain (Menu) 
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \returns -1 on failure, 1 if condition is true, 0 if condition is false
+ */
+int8_t dvdnav_is_domain_vtsm(dvdnav_t *self);
+/**
+ * Are we in the Video Title domain (playing movie)?
+ * \param self Pointer to dvdnav_t associated with this operation.
+ * \returns -1 on failure, 1 if condition is true, 0 if condition is false
+ */
+int8_t dvdnav_is_domain_vts(dvdnav_t *self);
 
 /**
- * Get active spu stream.
+ * @}
  */
-int8_t dvdnav_get_active_spu_stream(dvdnav_t *self);
+
+/*
+ * The following info appears on the front page of the reference manual. It is
+ * included here to keep it with the main dvdnav source files. The copyright notice
+ * refers to the comments _only_. All machine-readable source code is covered by
+ * the copyright notice at the top of this file.
+ *
+ * Oh, and the official language of the documentation is English -- 
+ * English English (as in the English spoken in England) not US English.
+ */
 
 /**
- * Get video aspect
- */
-uint8_t dvdnav_get_video_aspect(dvdnav_t *self);
-
-/* Following functions returns:
- *  -1 on failure,
- *   1 if condition is true,
- *   0 if condition is false
+ * \mainpage The libdvdnav Reference Documentation
+ *
+ * \section intro Introduction
+ * 
+ * This reference documentation is intended to both provide a comprehensive reference to
+ * the <tt>libdvdnav</tt> DVD navigation library and a brief introduction to the library
+ * for new users.
+ *
+ * This documentation is automatically generated from the <tt>libdvdnav</tt> code so
+ * should remain somewhat relevant but as always be wary that <tt>libdvdnav</tt>
+ * is currently in heavy development and the API is not yet frozen.
+ * 
+ * \subsection feedback Feedback
+ *
+ * All comments, error reports, additional information and criticism of all sorts
+ * should be directed to <tt>dvd-devel@lists.sf.net</tt>.
+ *
+ * \subsection disclaimer Disclaimer
+ *
+ * No liability for the contents of this documents can be accepted. Use the concepts, 
+ * examples and other content at your own risk. Additionally, this is an early version, 
+ * with many possibilities for inaccuracies and errors.
+ *
+ * As far as I know, all of the programmes mentioned here and example code quoted are 
+ * released under the GNU General Public License or the Lesser GNU Public License. 
+ *
+ * \subsection copyright Copyright information
+ *
+ * This document is copyrighted &copy;2002 by Richard Wareham and the <tt>libdvdnav</tt>
+ * project. It is distributed under the following terms:
+ * 
+ *   - This document may be reproduced and distributed in whole or in part, in any medium
+ *     physical or electronic, as long as this copyright notice is retained on all copies.
+ *     Commercial redistribution is allowed and encouraged; however, the author would like 
+ *     to be notified of any such distributions.
+ *   - All translations, derivative works, or aggregate works incorporating any parts of 
+ *     this document must be covered under this copyright notice. That is, you may not produce
+ *     a derivative work from this manual and impose additional restrictions on its distribution.
+ *
+ * \section started Getting started
+ *
+ * A good place to look is the <A HREF="modules.html">modules</a> section.
  */
-/***  Current VM domain state  ***/
-/* First Play domain. (Menu) */
-int8_t dvdnav_is_domain_fp(dvdnav_t *self);
-/* Video management Menu domain. (Menu) */
-int8_t dvdnav_is_domain_vmgm(dvdnav_t *self);
-/* Video Title Menu domain (Menu) */
-int8_t dvdnav_is_domain_vtsm(dvdnav_t *self);
-/* Video Title domain (playing movie). */
-int8_t dvdnav_is_domain_vts(dvdnav_t *self);
 
 #ifdef __cplusplus
 }
diff -r 131ad65a2398 -r 0ba15bf3dc25 dvdnav_events.h
--- a/dvdnav_events.h	Tue Jun 04 13:35:16 2002 +0000
+++ b/dvdnav_events.h	Thu Jun 06 15:03:09 2002 +0000
@@ -28,65 +28,87 @@
 #include <dvdread/nav_types.h>
 #include <dvdread/dvd_reader.h>
 
-/* This header defines events and event types */
+/**
+ * \file dvdnav_events.h
+ * This header defines events and event types 
+ */
 
 /*** EVENTS ***/
 
-#define DVDNAV_BLOCK_OK     0 /* The next black was returned */
-#define DVDNAV_NOP          1 /* No action should be taken   */
-#define DVDNAV_STILL_FRAME  2 /* The preceeding block was the last in a 
+#define DVDNAV_BLOCK_OK     0 /*!< The next black was returned */
+#define DVDNAV_NOP          1 /*!< No action should be taken   */
+#define DVDNAV_STILL_FRAME  2 /*!< The preceeding block was the last in a 
 				 still frame. */
-#define DVDNAV_SPU_STREAM_CHANGE    3 /* The SPU stream was changed */
-#define DVDNAV_AUDIO_STREAM_CHANGE  4 /* The Audio stream was changed */
-#define DVDNAV_VTS_CHANGE   5 /* We have changed VTS */ 
-#define DVDNAV_CELL_CHANGE  6 /* We have jumped to a new cell */
-#define DVDNAV_NAV_PACKET   7 /* The packet just passed was the NAV packet */
-#define DVDNAV_STOP         8 /* The last block was final, no more are coming */
-#define DVDNAV_HIGHLIGHT    9 /* Change highlight region */
-#define DVDNAV_SPU_CLUT_CHANGE 10 /* SPU CLUT */
-#define DVDNAV_SEEK_DONE    11 /* Seek done, subtitles should be reset */
-#define DVDNAV_HOP_CHANNEL  12 /* Sent when non-seemless stream change has happed */
-                               /* E.g. Menu button pressed causing change in menu */
+#define DVDNAV_SPU_STREAM_CHANGE    3 /*!< The SPU stream was changed */
+#define DVDNAV_AUDIO_STREAM_CHANGE  4 /*!< The Audio stream was changed */
+#define DVDNAV_VTS_CHANGE   5 /*!< We have changed VTS */ 
+#define DVDNAV_CELL_CHANGE  6 /*!< We have jumped to a new cell */
+#define DVDNAV_NAV_PACKET   7 /*!< The packet just passed was the NAV packet */
+#define DVDNAV_STOP         8 /*!< The last block was final, no more are coming */
+#define DVDNAV_HIGHLIGHT    9 /*!< Change highlight region */
+#define DVDNAV_SPU_CLUT_CHANGE 10 /*!< SPU CLUT */
+#define DVDNAV_SEEK_DONE    11 /*!< Seek done, subtitles should be reset */
+#define DVDNAV_HOP_CHANNEL  12 /*!< Sent when non-seemless stream change has happed 
+                                E.g. Menu button pressed causing change in menu */
 
 /*** EVENT TYPES ***/
 
+/**
+ * Structure providing information on DVDNAV_STILL_FRAME events.
+ */
 typedef struct {
-  int length;   /* The length (in seconds) the still frame
-		 * should be displayed for, or 0xff if
-		 * indefinate. */
+  int length;   /*!<
+		  The length (in seconds) the still frame
+		  should be displayed for, or 0xff if
+		  indefinate. */
 } dvdnav_still_event_t;
 
+/**
+ * Structure providing information on DVDNAV_*_STREAM_CHANGE events.
+ */
 typedef struct {
-  int physical; /* The physical (MPEG) stream number. */
-  int logical;  /* The logical (DVD) stream number.   */
+  int physical; /*!< The physical (MPEG) stream number. */
+  int logical;  /*!< The logical (DVD) stream number.   */
 } dvdnav_stream_change_event_t;
 
+/**
+ * Structure providing information on DVDNAV_VTS_CHANGE events.
+ */
 typedef struct {
-  int old_vtsN; /* The old VTS number */
-  dvd_read_domain_t old_domain; /* The old domain */
-  int new_vtsN; /* The new one */
-  dvd_read_domain_t new_domain;
+  int old_vtsN; /*!< The old VTS number */
+  dvd_read_domain_t old_domain; /*!< The old domain */
+  int new_vtsN; /*!< The new VTS number */
+  dvd_read_domain_t new_domain; /*!< The new domain */
 } dvdnav_vts_change_event_t;
 
+/**
+ * Structure providing information on DVDNAV_CELL_CHANGE events.
+ */
 typedef struct {
-  cell_playback_t *old_cell; /* The old cell (or NULL if this is 
+  cell_playback_t *old_cell; /*!< The old cell (or NULL if this is 
 				the first cell) */
-  cell_playback_t *new_cell; /* The cell_playback_t for the new cell */
+  cell_playback_t *new_cell; /*!< The cell_playback_t for the new cell */
 } dvdnav_cell_change_event_t;
 
+/**
+ * Structure providing information on DVDNAV_NAV_PACKET events.
+ */
 typedef struct {
   pci_t *pci;
   dsi_t *dsi;
 } dvdnav_nav_packet_event_t;
 
+/**
+ * Structure providing information on DVDNAV_HIGHLIGHT events.
+ */
 typedef struct {
-  int display; /* 0 - hide, 1 - show, entries below only guaranteed useful
+  int display; /*!< 0 - hide, 1 - show, entries below only guaranteed useful
 		  if this is '1' */
-  uint32_t palette;  /* The CLUT entries for the highlight palette 
+  uint32_t palette;  /*!< The CLUT entries for the highlight palette 
                         (4-bits per entry -> 4 entries) */
-  uint16_t sx,sy,ex,ey; /* The start/end x,y positions */
-  uint32_t pts;         /* Highlight PTS to match with SPU */
-  uint32_t buttonN;     /* Button number for the SPU decoder. */
+  uint16_t sx,sy,ex,ey; /*!< The start/end x,y positions */
+  uint32_t pts;         /*!< Highlight PTS to match with SPU */
+  uint32_t buttonN;     /*!< Button number for the SPU decoder. */
 } dvdnav_highlight_event_t;
 
 #endif /* DVDNAV_EVENTS_H_INCLUDED */