some markup and fixes

git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@10312 67ed7778-7388-44ab-90cf-0a291f65f57c

3 files changed, 22 insertions, 5 deletions

diff --git a/libgphoto2_port/gphoto2/gphoto2-port-library.h b/libgphoto2_port/gphoto2/gphoto2-port-library.h
index ef78b07a8..226f946b3 100644
--- a/libgphoto2_port/gphoto2/gphoto2-port-library.h
+++ b/libgphoto2_port/gphoto2/gphoto2-port-library.h
@@ -1,17 +1,20 @@
 /** \file gphoto2-port-library.h
  *
- * Copyright © 2001 Lutz Müller <lutz@users.sf.net>
+ * \author Copyright 2001 Lutz Müller <lutz@users.sf.net>
  *
+ * \par License
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2 of the License, or (at your option) any later version.
  *
+ * \par
  * This library 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.  See the GNU
  * Lesser General Public License for more details. 
  *
+ * \par
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
@@ -24,8 +27,16 @@
 #include <gphoto2/gphoto2-port-info-list.h>
 #include <gphoto2/gphoto2-port.h>
 
-typedef struct _GPPortOperations GPPortOperations;
-struct _GPPortOperations {
+/**
+ * \brief The port operations
+ * 
+ * These operations are to be implemented and set by the port library,
+ * which drives the lowlevel protocol (serial, usb, etc.).
+ *
+ * They are acessed using the accessor functions, like gp_port_open(),
+ * gp_port_read() and gp_port_write().
+ */
+typedef struct _GPPortOperations {
         int (*init)     (GPPort *);
         int (*exit)     (GPPort *);
         int (*open)     (GPPort *);
@@ -60,7 +71,7 @@ struct _GPPortOperations {
                                 int value, int index, char *bytes, int size);
         int (*msg_class_read) (GPPort * dev, int request, 
                                 int value, int index, char *bytes, int size);
-};
+} GPPortOperations;
 
 typedef GPPortType (* GPPortLibraryType) (void);
 typedef int (* GPPortLibraryList)       (GPPortInfoList *list);
diff --git a/libgphoto2_port/gphoto2/gphoto2-port-portability.h b/libgphoto2_port/gphoto2/gphoto2-port-portability.h
index 7013aca5d..b17a37fd5 100644
--- a/libgphoto2_port/gphoto2/gphoto2-port-portability.h
+++ b/libgphoto2_port/gphoto2/gphoto2-port-portability.h
@@ -173,7 +173,7 @@ typedef struct {
 # include <sys/stat.h>
 # include <unistd.h>
 
-/* Sleep functionality */
+/** Sleep passed amount of milliseconds. */
 # define GP_SYSTEM_SLEEP(_ms)			      \
   do {						      \
     const struct timespec req = {		      \
@@ -184,8 +184,11 @@ typedef struct {
   } while (0)
 
 /* Directory-oriented functions */
+/** A system directory handle */
 # define gp_system_dir           DIR *
+/** A system directory entry */
 # define gp_system_dirent	 struct dirent *
+/** The directory delimiter character on this platform. */
 # define gp_system_dir_delim	 '/'
 
 /************************************************************************
diff --git a/libgphoto2_port/gphoto2/gphoto2-port.h b/libgphoto2_port/gphoto2/gphoto2-port.h
index 3a4b241dc..817cec554 100644
--- a/libgphoto2_port/gphoto2/gphoto2-port.h
+++ b/libgphoto2_port/gphoto2/gphoto2-port.h
@@ -221,8 +221,11 @@ int         gp_port_set_error (GPPort *port, const char *format, ...)
 const char *gp_port_get_error (GPPort *port);
 
 /* DEPRECATED */
+/** \deprecated internal typedef */
 typedef GPPort gp_port;
+/** \deprecated internal typedef */
 typedef GPPortSettings gp_port_settings;
+/** \deprecated internal define */
 #define PIN_CTS GP_PIN_CTS
 
 #ifdef __cplusplus