From 24b74eb08b78488a5845059c1ab03740d3a03dbd Mon Sep 17 00:00:00 2001 From: rocky Date: Mon, 17 Nov 2003 12:06:56 +0000 Subject: [PATCH] Related to doxygen documentation. --- doc/Makefile.am | 5 ++++- include/cdio/cd_types.h | 10 +++++++-- include/cdio/cdio.h | 43 ++++++++++++++++++++++++++++-------- include/cdio/iso9660.h | 6 +++--- include/cdio/logging.h | 7 +++++- include/cdio/sector.h | 6 +++--- include/cdio/types.h | 7 +++++- include/cdio/xa.h | 48 +++++++++++++++++++++++++---------------- 8 files changed, 94 insertions(+), 38 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index cdfd8f83..fa7adba6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -# $Id: Makefile.am,v 1.3 2003/11/16 19:30:45 rocky Exp $ +# $Id: Makefile.am,v 1.4 2003/11/17 12:06:56 rocky Exp $ # # Copyright (C) 2003 Rocky Bernstein # @@ -19,6 +19,9 @@ EXTRA_DIST = doxygen/Doxyfile doxygen/run_doxygen info_TEXINFOS = libcdio.texi +reference: + -( cd ${top_srcdir} && $(MAKE) doxygen ) + pdf: libcdio.pdf txt: libcdio.txt diff --git a/include/cdio/cd_types.h b/include/cdio/cd_types.h index 4d0bb74c..537a4018 100644 --- a/include/cdio/cd_types.h +++ b/include/cdio/cd_types.h @@ -1,5 +1,5 @@ /* - $Id: cd_types.h,v 1.6 2003/11/05 04:12:58 rocky Exp $ + $Id: cd_types.h,v 1.7 2003/11/17 12:06:57 rocky Exp $ Copyright (C) 2003 Rocky Bernstein Copyright (C) 1996,1997,1998 Gerd Knorr @@ -20,6 +20,12 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** \file cd_types.h + * \brief Header for routines which automatically determine the Compact Disc + * format and possibly filesystem on the CD. + * + */ + #ifndef __CDIO_CD_TYPES_H__ #define __CDIO_CD_TYPES_H__ @@ -115,7 +121,7 @@ typedef struct /** * Try to determine what kind of CD-image and/or filesystem we * have at track track_num. Return information about the CD image - * is returned in cdio_analysis and the return value. + * is returned in iso_analysis and the return value. */ cdio_fs_anal_t cdio_guess_cd_type(const CdIo *cdio, int start_session, track_t track_num, diff --git a/include/cdio/cdio.h b/include/cdio/cdio.h index 45ca6094..bd3914b7 100644 --- a/include/cdio/cdio.h +++ b/include/cdio/cdio.h @@ -1,5 +1,5 @@ /* -*- c -*- - $Id: cdio.h,v 1.33 2003/11/05 12:40:34 rocky Exp $ + $Id: cdio.h,v 1.34 2003/11/17 12:06:57 rocky Exp $ Copyright (C) 2001 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -19,7 +19,9 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/** \file cdio.h - Public CD Input and Control Interface . */ +/** \file cdio.h + * \brief The top-level header for libcdio: the CD Input and Control library. + */ #ifndef __CDIO_H__ @@ -46,7 +48,7 @@ #define CDIO_SRC_IS_DISK_IMAGE_MASK 0x0001 /**< Read source is a CD image. */ #define CDIO_SRC_IS_DEVICE_MASK 0x0002 /**< Read source is a CD device. */ -#define CDIO_SRC_IS_SCSI_MASK 0x0004 +#define CDIO_SRC_IS_SCSI_MASK 0x0004 #define CDIO_SRC_IS_NATIVE_MASK 0x0008 #ifdef __cplusplus @@ -392,29 +394,40 @@ extern "C" { the some sort of device name. NULL is returned on error or there is no BSDI driver. + + @see cdio_open */ CdIo * cdio_open_bsdi (const char *source_name); /*! Return a string containing the default device name that the BSDI driver would use when none is specified. - NULL is returned on error or there is no CD-ROM device + NULL is returned on error or there is no CD-ROM device. + + @see cdio_open_cd + @see cdio_open */ char * cdio_get_default_device_bsdi(void); + /*! Return a list of all of the CD-ROM devices that the BSDI driver + can find. + */ char **cdio_get_devices_bsdi(void); /*! Set up CD-ROM for reading using the FreeBSD driver. The device_name is the some sort of device name. NULL is returned on error or there is no FreeBSD driver. + + @see cdio_open_cd + @see cdio_open */ CdIo * cdio_open_freebsd (const char *source_name); /*! Return a string containing the default device name that the FreeBSD driver would use when none is specified. - NULL is returned on error or there is no CD-ROM device + NULL is returned on error or there is no CD-ROM device. */ char * cdio_get_default_device_freebsd(void); @@ -434,7 +447,10 @@ extern "C" { GNU/Linux driver would use when none is specified. A scan is made for CD-ROM drives with CDs in them. - NULL is returned on error or there is no CD-ROM device + NULL is returned on error or there is no CD-ROM device. + + @see cdio_open_cd + @see cdio_open */ char * cdio_get_default_device_linux(void); @@ -454,7 +470,10 @@ extern "C" { Solaris driver would use when none is specified. A scan is made for CD-ROM drives with CDs in them. - NULL is returned on error or there is no CD-ROM device + NULL is returned on error or there is no CD-ROM device. + + @see cdio_open_cd + @see cdio_open */ char * cdio_get_default_device_solaris(void); @@ -467,6 +486,9 @@ extern "C" { device_name is the some sort of device name. NULL is returned on error or there is no OSX driver. + + @see cdio_open_cd + @see cdio_open */ CdIo * cdio_open_osx (const char *source_name); @@ -494,7 +516,10 @@ extern "C" { Win32 driver would use when none is specified. A scan is made for CD-ROM drives with CDs in them. - NULL is returned on error or there is no CD-ROM device + NULL is returned on error or there is no CD-ROM device. + + @see cdio_open_cd + @see cdio_open */ char * cdio_get_default_device_win32(void); @@ -511,7 +536,7 @@ extern "C" { NRG driver would use when none is specified. A scan is made for NRG disk images in the current directory.. - NULL is returned on error or there is no CD-ROM device + NULL is returned on error or there is no CD-ROM device. */ char * cdio_get_default_device_nrg(void); diff --git a/include/cdio/iso9660.h b/include/cdio/iso9660.h index 1c679d59..1ab8c9b8 100644 --- a/include/cdio/iso9660.h +++ b/include/cdio/iso9660.h @@ -1,5 +1,5 @@ /* - $Id: iso9660.h,v 1.31 2003/11/16 19:30:45 rocky Exp $ + $Id: iso9660.h,v 1.32 2003/11/17 12:06:57 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -24,8 +24,8 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ /*! - * \file iso9660.h - Assorted structure definitions and typecasts. - * specific for the ISO 9660 filesystem. + * \file iso9660.h + * \brief Header for libiso9660: the ISO-9660 filesystem library. */ diff --git a/include/cdio/logging.h b/include/cdio/logging.h index c267f9b5..874e85e0 100644 --- a/include/cdio/logging.h +++ b/include/cdio/logging.h @@ -1,5 +1,5 @@ /* - $Id: logging.h,v 1.5 2003/11/04 12:28:08 rocky Exp $ + $Id: logging.h,v 1.6 2003/11/17 12:06:58 rocky Exp $ Copyright (C) 2000, Herbert Valerio Riedel Copyright (C) 2003, Rocky Bernstein @@ -18,6 +18,11 @@ along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ + +/** \file logging.h + * \brief Header to control logging and level of detail of output. + * + */ #ifndef __LOGGING_H__ #define __LOGGING_H__ diff --git a/include/cdio/sector.h b/include/cdio/sector.h index 7a2f4468..e055cb46 100644 --- a/include/cdio/sector.h +++ b/include/cdio/sector.h @@ -1,5 +1,5 @@ /* - $Id: sector.h,v 1.7 2003/11/05 12:40:35 rocky Exp $ + $Id: sector.h,v 1.8 2003/11/17 12:06:58 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -19,8 +19,8 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ /*! - \file sector.h - Things related to CDROM layout. Sector sizes, - MSFs, LBAs, + \file sector.h + \brief Things related to CD-ROM layout: tracks, sector sizes, MSFs, LBAs. A CD-ROM physical sector size is 2048, 2052, 2056, 2324, 2332, 2336, 2340, or 2352 bytes long. diff --git a/include/cdio/types.h b/include/cdio/types.h index 3fa214ee..1af9d981 100644 --- a/include/cdio/types.h +++ b/include/cdio/types.h @@ -1,5 +1,5 @@ /* - $Id: types.h,v 1.7 2003/09/28 17:14:20 rocky Exp $ + $Id: types.h,v 1.8 2003/11/17 12:06:58 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2002,2003 Rocky Bernstein @@ -18,6 +18,11 @@ along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ + +/** \file types.h + * \brief Common type definitions used pervasively in libcdio. + */ + #ifndef __CDIO_TYPES_H__ #define __CDIO_TYPES_H__ diff --git a/include/cdio/xa.h b/include/cdio/xa.h index 600a794a..9b5984e9 100644 --- a/include/cdio/xa.h +++ b/include/cdio/xa.h @@ -1,5 +1,5 @@ /* - $Id: xa.h,v 1.5 2003/09/21 01:14:30 rocky Exp $ + $Id: xa.h,v 1.6 2003/11/17 12:06:58 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -24,6 +24,11 @@ along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/*! + \file xa.h + \brief Things related to the ISO-9660 XA (Extended Attributes) format +*/ + #ifndef __CDIO_XA_H__ #define __CDIO_XA_H__ @@ -34,17 +39,17 @@ #define ISO_XA_MARKER_OFFSET 1024 /* XA attribute definitions */ -#define XA_PERM_RSYS 0x0001 /* System Group Read */ -#define XA_PERM_XSYS 0x0004 /* System Group Execute */ +#define XA_PERM_RSYS 0x0001 /**< System Group Read */ +#define XA_PERM_XSYS 0x0004 /**< System Group Execute */ -#define XA_PERM_RUSR 0x0010 /* User (owner) Read */ -#define XA_PERM_XUSR 0x0040 /* User (owner) Execute */ +#define XA_PERM_RUSR 0x0010 /**< User (owner) Read */ +#define XA_PERM_XUSR 0x0040 /**< User (owner) Execute */ -#define XA_PERM_RGRP 0x0100 /* Group Read */ -#define XA_PERM_XGRP 0x0400 /* Group Execute */ +#define XA_PERM_RGRP 0x0100 /**< Group Read */ +#define XA_PERM_XGRP 0x0400 /**< Group Execute */ -#define XA_PERM_ROTH 0x1000 /* Other (world) Read */ -#define XA_PERM_XOTH 0x4000 /* Other (world) Execute */ +#define XA_PERM_ROTH 0x1000 /**< Other (world) Read */ +#define XA_PERM_XOTH 0x4000 /**< Other (world) Execute */ #define XA_ATTR_MODE2FORM1 (1 << 11) #define XA_ATTR_MODE2FORM2 (1 << 12) @@ -61,17 +66,18 @@ #define XA_FORM1_FILE (XA_ATTR_MODE2FORM1 | XA_PERM_ALL_ALL) #define XA_FORM2_FILE (XA_ATTR_MODE2FORM2 | XA_PERM_ALL_ALL) -/* - * Extended Attributes record according to Yellow Book. +/*! + * An "Extended Attributes" record according to the Philips Yellow Book. + * Note structure is big-endian. */ -typedef struct iso9660_xa /* big endian!! */ +typedef struct iso9660_xa { - uint16_t group_id; /* 0 */ - uint16_t user_id; /* 0 */ - uint16_t attributes; /* XA_ATTR_ */ - uint8_t signature[2]; /* { 'X', 'A' } */ - uint8_t filenum; /* file number, see also XA subheader */ - uint8_t reserved[5]; /* zero */ + uint16_t group_id; /**< 0 */ + uint16_t user_id; /**< 0 */ + uint16_t attributes; /**< XA_ATTR_ */ + uint8_t signature[2]; /**< { 'X', 'A' } */ + uint8_t filenum; /**< file number, see also XA subheader */ + uint8_t reserved[5]; /**< zero */ } iso9660_xa_t GNUC_PACKED; @@ -106,6 +112,12 @@ typedef struct iso9660_xa /* big endian!! */ const char * iso9660_get_xa_attr_str (uint16_t xa_attr); +/*! + Allocates and initalizes a new iso9600_xa_t variable and returns + it. The caller should free the returned result. + + @see iso9660_xa +*/ iso9660_xa_t * iso9660_xa_init (iso9660_xa_t *_xa, uint16_t uid, uint16_t gid, uint16_t attr, uint8_t filenum);