More documentation changes.

Makefile.am: Don't build man pages if not in MAINTAINER mode.

include/cdio/cd_types.h

@@ -1,5 +1,5 @@
 /*
-    $Id: cd_types.h,v 1.7 2003/11/17 12:06:57 rocky Exp $
+    $Id: cd_types.h,v 1.8 2003/11/18 03:35:19 rocky Exp $
 
     Copyright (C) 2003 Rocky Bernstein <rocky@panix.com>
     Copyright (C) 1996,1997,1998  Gerd Knorr <kraxel@bytesex.org>
@@ -104,10 +104,11 @@ extern "C" {
 #define CDIO_FS_MATCH_ALL            (cdio_fs_anal_t) (~CDIO_FS_MASK)
 
 
-/**
+/*!
- * The type used to return analysis information from
+  \brief The type used to return analysis information from
- * cdio_guess_cd_type. These fields make sense only for when an ISO 9660
+  cdio_guess_cd_type. 
- * filesystem is used.
+
+  These fields make sense only for when an ISO-9660 filesystem is used.
  */
 typedef struct 
 {

include/cdio/iso9660.h

@@ -1,5 +1,5 @@
 /*
-    $Id: iso9660.h,v 1.32 2003/11/17 12:06:57 rocky Exp $
+    $Id: iso9660.h,v 1.33 2003/11/18 03:35:19 rocky Exp $
 
     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
     Copyright (C) 2003 Rocky Bernstein <rocky@panix.com>
@@ -45,7 +45,7 @@
 /*!
    An ISO filename is: "abcde.eee;1" -> <filename> '.' <ext> ';' <version #>
 
-    The maximum needed string length is:
+    For ISO-9660 Level 1, the maximum needed string length is:
 
 \verbatim  
   	 30 chars (filename + ext)
@@ -100,6 +100,11 @@ enum strncpy_pad_check {
 
 PRAGMA_BEGIN_PACKED
 
+/*! 
+  \brief ISO-9660 shorter-format time structure.
+  
+  @see iso9660_dtime
+ */
 struct	iso9660_dtime {
   uint8_t 	dt_year;
   uint8_t 	dt_month;  /**< Has value in range 1..12. Note starts
@@ -114,7 +119,10 @@ struct	iso9660_dtime {
 
 typedef struct iso9660_dtime  iso9660_dtime_t;
 
-/*! ISO-9660 Primary Volume Descriptor.
+/*! 
+  \brief ISO-9660 longer-format time structure.
+  
+  @see iso9660_ltime
  */
 struct	iso9660_ltime {
   char	 lt_year	[_delta(   1,	4)];   /**< Add 1900 to value
@@ -136,7 +144,8 @@ struct	iso9660_ltime {
 
 typedef struct iso9660_ltime  iso9660_ltime_t;
 
-/*! ISO-9660 Primary Volume Descriptor.
+/*! 
+  \brief ISO-9660 Primary Volume Descriptor.
  */
 struct iso9660_pvd {
   uint8_t          type;                      /**< 711 encoded */
@@ -193,17 +202,19 @@ typedef struct iso9660_stat iso9660_stat_t;
 #define EMPTY_ARRAY_SIZE 0
 #endif
 
-/*
- * XXX JS: The next structure may have an odd length depending on how 
- * many characters there are in the filename!
- * Some compilers (e.g. on Sun3/mc68020) padd the structures to even length.
- * For this reason, we cannot use sizeof (struct iso_path_table) or
- * sizeof (struct iso_directory_record) to compute on disk sizes.
- * Instead, we use offsetof(..., name) and add the name size.
- * See mkisofs.h
- */
 
-/*! Format of an ISO-9660 directory record */
+/*! \brief Format of an ISO-9660 directory record 
+
+ This structure may have an odd length depending on how many
+ characters there are in the filename!  Some compilers (e.g. on
+ Sun3/mc68020) pad the structures to an even length.  For this reason,
+ we cannot use sizeof (struct iso_path_table) or sizeof (struct
+ iso_directory_record) to compute on disk sizes.  Instead, we use
+ offsetof(..., name) and add the name size.  See mkisofs.h of the 
+ cdrtools package.
+
+  @see iso9660_stat
+*/
 struct iso9660_dir {
   uint8_t          length;            /*! 711 encoded */
   uint8_t          xa_length;         /*! 711 encoded */
@@ -219,9 +230,14 @@ struct iso9660_dir {
 } GNUC_PACKED;
 
 
-/*! The iso9660_stat structure is not part of any ISO 9660 spec. We
+/*! \brief Unix stat-like version of iso9660_dir
-   just use it for our own purposes for communicating info back that's
+
-   pulled out.
+   The iso9660_stat structure is not part of the ISO-9660
+   specification. We use it for our to communicate information
+   in a C-library friendly way, e.g struct tm time structures and
+   a C-style filename string.
+
+   @see iso9660_dir
 */
 struct iso9660_stat { /* big endian!! */
   enum { _STAT_FILE = 1, _STAT_DIR = 2 } type;

include/cdio/types.h

@@ -1,5 +1,5 @@
 /*
-    $Id: types.h,v 1.8 2003/11/17 12:06:58 rocky Exp $
+    $Id: types.h,v 1.9 2003/11/18 03:35:19 rocky Exp $
 
     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
     Copyright (C) 2002,2003 Rocky Bernstein <rocky@panix.com>
@@ -177,14 +177,23 @@ extern "C" {
   /* our own offsetof()-like macro */
 #define __cd_offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER)
   
-  /* In many structures on the disk a sector address is stored as a
+  /*!
-     BCD-encoded mmssff in three bytes. */
+    \brief MSF (minute/second/frame) structure 
+
+    One CD-ROMs addressing scheme especially used in audio formats
+    (Red Book) is an address by minute, sector and frame which
+    BCD-encoded in three bytes. An alternative format is an lba_t.
+    
+    @see lba_t
+  */
   PRAGMA_BEGIN_PACKED
-  typedef struct {
+  struct msf_rec {
     uint8_t m, s, f;
-  } GNUC_PACKED msf_t;
+  } GNUC_PACKED;
   PRAGMA_END_PACKED
   
+  typedef struct msf_rec msf_t;
+
 #define msf_t_SIZEOF 3
   
   /* type used for bit-fields in structs (1 <= bits <= 8) */
@@ -199,13 +208,16 @@ extern "C" {
   typedef uint8_t bitfield_t;
 #endif
   
-  /* The type of a Logical Block Address. */
+  /*! The type of a Logical Block Address. 
+
+    @see msf_t
+  */
   typedef uint32_t lba_t;
   
-  /* The type of an Logical Sector Number. */
+  /*! The type of an Logical Sector Number. */
   typedef uint32_t lsn_t;
   
-  /* The type of an track number 0..99. */
+  /*! The type of an track number 0..99. */
   typedef uint8_t track_t;
   
   /*! 

include/cdio/util.h

@@ -1,5 +1,5 @@
 /*
-    $Id: util.h,v 1.1 2003/04/19 08:29:14 rocky Exp $
+    $Id: util.h,v 1.2 2003/11/18 03:35:19 rocky Exp $
 
     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
 
@@ -21,6 +21,12 @@
 #ifndef __CDIO_UTIL_H__
 #define __CDIO_UTIL_H__
 
+/*!
+   \file util.h 
+   \brief Miscellaneous utility functions. 
+
+   Warning: this will probably get removed/replaced by using glib.h
+*/
 #include <stdlib.h>
 
 #undef  MAX

src/Makefile.am

@@ -1,4 +1,4 @@
-#   $Id: Makefile.am,v 1.17 2003/09/22 01:00:10 rocky Exp $
+#   $Id: Makefile.am,v 1.18 2003/11/18 03:35:19 rocky Exp $
 #
 #    Copyright (C) 2003 Rocky Bernstein <rocky@panix.com>
 #
@@ -21,8 +21,14 @@
 ####################################################
 CDDB_LIBS=@CDDB_LIBS@
 
-if BUILD_CDINFO
+if MAINTAINER_MODE
+MAINTAINERCLEANFILES = $(man_MANS)
 man_MANS = cd-info.1 cd-read.1 
+$(man_MANS): %.1: %
+	-$(HELP2MAN) --output=$@ ./$<
+endif
+
+if BUILD_CDINFO
 cd_info_SOURCES = cd-info.c util.c util.h
 cd_info_LDADD =  $(LIBISO9660_LIBS) $(LIBCDIO_LIBS) $(LIBPOPT_LIBS) $(CDDB_LIBS) $(VCDINFO_LIBS)
 
@@ -43,7 +49,3 @@ man_MANS =
 endif
 
 INCLUDES = -I$(top_srcdir) $(LIBPOPT_CFLAGS) $(LIBCDIO_CFLAGS) $(VCDINFO_CFLAGS)
-if MAINTAINER_MODE
-$(man_MANS): %.1: %
-	-$(HELP2MAN) --output=$@ ./$<
-endif