touch up code documentation syntax and grammar

Author: rdmark

etc/afpd/volume.c

@@ -156,11 +156,11 @@ static long long int get_tm_bands(const char *path)
  *
  * This assumes that the volume is used only for TimeMachine.
  *
- * 1) readdir(path of volume)
- * 2) for every element that matches regex "\(.*\)\.sparsebundle$" :
- * 3) parse "\1.sparsebundle/Info.plist" and read the band-size XML key integer value
- * 4) readdir "\1.sparsebundle/bands/" counting files
- * 5) calculate used size as: (file_count - 1) * band-size
+ * 1. readdir(path of volume)
+ * 2. for every element that matches regex "\(.*\)\.sparsebundle$" :
+ * 3. parse "\1.sparsebundle/Info.plist" and read the band-size XML key integer value
+ * 4. readdir "\1.sparsebundle/bands/" counting files
+ * 5. calculate used size as: (file_count - 1) * band-size
  *
  * The result of the calculation is returned in "volume->v_tm_used".
  * "volume->v_appended" gets reset to 0.

etc/cnid_dbd/dbif.c

@@ -130,7 +130,7 @@ static int dbif_init_rootinfo(DBD *dbd, int version)
  *
  * Returns version in *version
  *
- * @returns -1 on error, 0 if theres no rootinfo key yet, 1 if *version is returned
+ * @returns -1 on error, 0 if there's no rootinfo key yet, 1 if *version is returned
  */
 static int dbif_getversion(DBD *dbd, uint32_t *version)
 {

etc/cnid_dbd/main.c

@@ -89,15 +89,16 @@ static void block_sigs_onoff(int block)
  * @brief Get lock on db lock file
  *
  * @param cmd      (r) lock command:
- *                     LOCK_FREE:   close lockfd
- *                     LOCK_UNLOCK: unlock lockm keep lockfd open
- *                     LOCK_EXCL:   F_WRLCK on lockfd
- *                     LOCK_SHRD:   F_RDLCK on lockfd
+ *                     - LOCK_FREE:   close lockfd
+ *                     - LOCK_UNLOCK: unlock lockm keep lockfd open
+ *                     - LOCK_EXCL:   F_WRLCK on lockfd
+ *                     - LOCK_SHRD:   F_RDLCK on lockfd
  * @param dbpath   (r) path to lockfile, only used on first call,
  *                     later the stored fd is used
- * @returns            LOCK_FREE/LOCK_UNLOCK return 0 on success, -1 on error
- *                     LOCK_EXCL/LOCK_SHRD return LOCK_EXCL or LOCK_SHRD respectively on
- *                     success, 0 if the lock couldn't be acquired, -1 on other errors
+ * @returns        depending on lock command:
+ *                     - LOCK_FREE/LOCK_UNLOCK return 0 on success, -1 on error
+ *                     - LOCK_EXCL/LOCK_SHRD return LOCK_EXCL or LOCK_SHRD respectively on
+ *                       success, 0 if the lock couldn't be acquired, -1 on other errors
  */
 static int get_lock(int cmd, const char *dbpath)
 {

include/atalk/list.h

@@ -134,7 +134,7 @@ static inline void list_splice(struct list_head *list, struct list_head *head)
 
 #endif
 /*!
- * @brief list_entry - get the struct for this entry
+ * @brief get the struct for this entry
  * @param ptr       the &struct list_head pointer.
  * @param type      the type of the struct this is embedded in.
  * @param member    the name of the list_struct within the struct.
@@ -143,7 +143,7 @@ static inline void list_splice(struct list_head *list, struct list_head *head)
     ((type *)((char *)(ptr)-(unsigned long)(&((type *)0)->member)))
 
 /*!
- * @brief list_for_each	-	iterate over a list
+ * @brief iterate over a list
  * @param pos       the &struct list_head to use as a loop counter.
  * @param head      the head for your list.
  */
@@ -152,7 +152,7 @@ static inline void list_splice(struct list_head *list, struct list_head *head)
         pos = pos->next)
 
 /*!
- * @brief list_for_each_prev	-	iterate over a list in reverse order
+ * @brief iterate over a list in reverse order
  * @param pos       the &struct list_head to use as a loop counter.
  * @param head      the head for your list.
  */

libatalk/acl/ldap.c

@@ -103,15 +103,16 @@ struct pref_array prefs_array[] = {
  * Static helper function
  ********************************************************/
 
-/*
+/*!
+ * @brief LDAP get attribute from filter with base and scope
  * ldap_getattr_fromfilter_withbase_scope():
  *   conflags: KEEPALIVE
  *   scope: LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, LDAP_SCOPE_SUBTREE
  *   result: return unique search result here, allocated here, caller must free
  *
- * returns: -1 on error
- *           0 nothing found
- *           1 successfull search, result int 'result'
+ * @returns: -1 on error,
+ *           0 nothing found,
+ *           1 successful search, result int 'result'
  *
  * All connection managment to the LDAP server is done here. Just set KEEPALIVE if you know
  * you will be dispatching more than one search in a row, then don't set it with the last search.
@@ -437,16 +438,17 @@ int ldap_getuuidfromname(const char *name, uuidtype_t type, char **uuid_string)
     return 0;
 }
 
-/*
- * LDAP search wrapper
+/*!
+ * @brief LDAP search wrapper
+ *
  * returns allocated storage in name, caller must free it
  * returns 0 on success, -1 on error or not found
  *
  * @param uuidstr  (r) uuid to search as ascii string
  * @param name     (w) return pointer to name as allocated string
  * @param type     (w) return type: USER or GROUP
  *
- * returns 0 on success, -1 on errror
+ * @returns 0 on success, -1 on errror
  */
 int ldap_getnamefromuuid(const char *uuidstr, char **name, uuidtype_t *type)
 {

libatalk/acl/unix.c

@@ -223,16 +223,16 @@ int strip_nontrivial_aces(ace_t **saces, int sacecount)
  * @brief Change mode of file preserving existing explicit ACEs
  *
  * nfsv4_chmod
- * (1) reads objects ACL (acl1), may return 0 or -1 NFSv4 ACEs on e.g. UFS fs
- * (2) removes all trivial ACEs from the ACL by calling strip_trivial_aces(), possibly
- *     leaving 0 ACEs in the ACL if there were only trivial ACEs as mapped from the mode
- * (3) calls chmod() with mode, we're done if step (1) returned 0 for noaces
- * (4) reads the changed ACL (acl2) which
- *     a) might still contain explicit ACEs (up to onnv132)
- *     b) will have any explicit ACE removed (starting with onnv145/Openindiana)
- * (5) strip any explicit ACE from acl2 using strip_nontrivial_aces()
- * (6) merge acl2 and acl2
- * (7) set the ACL merged ACL on the object
+ * 1. reads objects ACL (acl1), may return 0 or -1 NFSv4 ACEs on e.g. UFS fs
+ * 2. removes all trivial ACEs from the ACL by calling strip_trivial_aces(), possibly
+ *    leaving 0 ACEs in the ACL if there were only trivial ACEs as mapped from the mode
+ * 3. calls chmod() with mode, we're done if step (1) returned 0 for noaces
+ * 4. reads the changed ACL (acl2) which
+ *    a. might still contain explicit ACEs (up to onnv132)
+ *    b. will have any explicit ACE removed (starting with onnv145/Openindiana)
+ * 5. strip any explicit ACE from acl2 using strip_nontrivial_aces()
+ * 6. merge acl2 and acl2
+ * 7. set the ACL merged ACL on the object
  */
 int nfsv4_chmod(char *name, mode_t mode)
 {

libatalk/adouble/ad_open.c

@@ -2251,10 +2251,12 @@ void ad_init(struct adouble *ad, const struct vol *restrict vol)
 /*!
  * @brief Open data-, metadata(header)- or resource fork
  *
+ * @code
  * ad_open(struct adouble *ad, const char *path, int adflags, int flags)
  * ad_open(struct adouble *ad, const char *path, int adflags, int flags, mode_t mode)
+ * @endcode
  *
- * You must call ad_init() before ad_open, usually you'll just call it like this: \n
+ * You must call ad_init() before ad_open, usually you'll just call it like this:
  * @code
  *      struct adoube ad;
  *      ad_init(&ad, vol->v_adouble, vol->v_ad_options);
@@ -2264,29 +2266,32 @@ void ad_init(struct adouble *ad, const struct vol *restrict vol)
  *
  * @param ad        (rw) pointer to struct adouble
  * @param path      (r)  Path to file or directory
- * @param adflags   (r)  Flags specifying which fork to open, can be or'd:
- *                         ADFLAGS_DF:        open data fork
- *                         ADFLAGS_RF:        open resource fork
- *                         ADFLAGS_HF:        open header (metadata) file
- *                         ADFLAGS_NOHF:      it's not an error if header file couldn't be opened
- *                         ADFLAGS_NORF:      it's not an error if reso fork couldn't be opened
- *                         ADFLAGS_DIR:       if path is a directory you MUST or ADFLAGS_DIR to adflags
+ * @param adflags   (r)  Flags specifying which fork to open, can be or'd (see below)
+ * @param ...       (r)  mode used with O_CREATE
+ * 
+ * Regular adflags:
+ *  - ADFLAGS_DF:        open data fork
+ *  - ADFLAGS_RF:        open resource fork
+ *  - ADFLAGS_HF:        open header (metadata) file
+ *  - ADFLAGS_NOHF:      it's not an error if header file couldn't be opened
+ *  - ADFLAGS_NORF:      it's not an error if reso fork couldn't be opened
+ *  - ADFLAGS_DIR:       if path is a directory you MUST or ADFLAGS_DIR to adflags
  *
- *                       Access mode for the forks:
- *                         ADFLAGS_RDONLY:    open read only
- *                         ADFLAGS_RDWR:      open read write
+ * Access mode for the forks:
+ *  - ADFLAGS_RDONLY:    open read only
+ *  - ADFLAGS_RDWR:      open read write
  *
- *                       Creation flags:
- *                         ADFLAGS_CREATE:    create if not existing
- *                         ADFLAGS_TRUNC:     truncate
+ * Creation flags:
+ *  - ADFLAGS_CREATE:    create if not existing
+ *  - ADFLAGS_TRUNC:     truncate
  *
- *                       Special flags:
- *                         ADFLAGS_CHECK_OF:  check for open forks from us and other afpd's
- *                         ADFLAGS_SETSHRMD:  this adouble struct will be used to set sharemode locks.
- *                                            This basically results in the files being opened RW instead of RDONLY.
- * @param ...       (r)  mode used with O_CREATE
+ * Special flags:
+ *  - ADFLAGS_CHECK_OF:  check for open forks from us and other afpd's
+ *  - ADFLAGS_SETSHRMD:  this adouble struct will be used to set sharemode locks.
+ *                       This basically results in the files being opened RW instead of RDONLY.
  *
  * The open mode flags (rw vs ro) have to take into account all the following requirements:
+ * 
  * - we remember open fds for files because me must avoid a single close releasing fcntl locks for other
  *   fds of the same file
  *