From ad10dc0aadf74983abae6df81e5b5963f1199e55 Mon Sep 17 00:00:00 2001
From: franklahm <franklahm>
Date: Mon, 4 Jan 2010 13:49:48 +0000
Subject: [PATCH] Start adouble documentation in Doxygen style

---
 include/atalk/adouble.h    |  7 ++++-
 libatalk/adouble/ad_open.c | 52 +++++++++++++++++++++++++++++++++-----
 2 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/include/atalk/adouble.h b/include/atalk/adouble.h
index 0ac822a4..0c420d04 100644
--- a/include/atalk/adouble.h
+++ b/include/atalk/adouble.h
@@ -1,5 +1,5 @@
 /*
- * $Id: adouble.h,v 1.50 2009-11-18 11:14:59 didg Exp $
+ * $Id: adouble.h,v 1.51 2010-01-04 13:49:48 franklahm Exp $
  * Copyright (c) 1990,1991 Regents of The University of Michigan.
  * All Rights Reserved.
  *
@@ -22,6 +22,11 @@
  *  netatalk@itd.umich.edu
  */
 
+/*!
+ * @file
+ * @brief Part of Netatalk's AppleDouble implementatation
+ */
+
 #ifndef _ATALK_ADOUBLE_H
 #define _ATALK_ADOUBLE_H
 
diff --git a/libatalk/adouble/ad_open.c b/libatalk/adouble/ad_open.c
index a3043866..5b3f93c4 100644
--- a/libatalk/adouble/ad_open.c
+++ b/libatalk/adouble/ad_open.c
@@ -1,5 +1,5 @@
 /*
- * $Id: ad_open.c,v 1.60 2009-11-27 12:37:25 didg Exp $
+ * $Id: ad_open.c,v 1.61 2010-01-04 13:49:48 franklahm Exp $
  *
  * Copyright (c) 1999 Adrian Sun (asun@u.washington.edu)
  * Copyright (c) 1990,1991 Regents of The University of Michigan.
@@ -23,8 +23,14 @@
  *  +1-313-763-0525
  *  netatalk@itd.umich.edu
  *
- * NOTE: I don't use inline because a good compiler should be
- * able to optimize all the static below. Didier
+ */
+
+/*!
+ * @file
+ * Part of Netatalk's AppleDouble implementatation
+ * @note We don't use inlines because a good compiler should be
+ *       able to optimize all the static funcs below.
+ * @sa include/atalk/adouble.h
  */
 
 #ifdef HAVE_CONFIG_H
@@ -1204,9 +1210,43 @@ void ad_init(struct adouble *ad, int flags, int options)
     ad->ad_rlen = 0;
 }
 
-/* -------------------
- * It's not possible to open the header file O_RDONLY -- the read
- * will fail and return an error. this refcounts things now.
+/*!
+ * Open data-, metadata(header)- or ressource fork
+ *
+ * You must call ad_init() before ad_open, usually you'll just call it like this: \n
+ * @code
+ *      struct adoube ad;
+ *      ad_init(&ad, vol->v_adouble, vol->v_ad_options);
+ * @endcode
+ *
+ * @param path    Path to file or directory
+ *
+ * @param adflags ADFLAGS_DF: open data file/fork\n
+ *                ADFLAGS_HF: open header (metadata) file\n
+ *                ADFLAGS_RF: open ressource fork *** FIXME: not used ?! *** \n
+ *                ADFLAGS_CREATE: indicate creation\n
+ *                ADFLAGS_NOHF: it's not an error if header file couldn't be created\n
+ *                ADFLAGS_DIR: if path is a directory you MUST or ADFLAGS_DIR to adflags\n
+ *                ADFLAGS_NOADOUBLE: dont create adouble files if not necessary\n
+ *                ADFLAGS_RDONLY: open read only\n
+ *                ADFLAGS_OPENFORKS: check for open forks from other processes\n
+ *                ADFLAGS_MD: alias for ADFLAGS_HF\n
+ *                ADFLAGS_V1COMPAT: obsolete
+ *
+ * @param oflags  flags passed through to open syscall: \n
+ *                O_RDONLY: *** FIXME *** \n
+ *                O_RDWR: *** FIXME *** \n
+ *                O_CREAT: create fork\n
+ *                O_EXCL: fail if exists with O_CREAT
+ *
+ * @param mode    passed to open with O_CREAT
+ *
+ * @param ad      pointer to struct adouble
+ *
+ * @returns 0 on success
+ *
+ * @note It's not possible to open the header file O_RDONLY -- the read
+ *       will fail and return an error. this refcounts things now.
  */
 int ad_open( const char *path, int adflags, int oflags, int mode, struct adouble  *ad)
 {
-- 
2.39.2