improve code documentation and remove dead code

.github/workflows/test.yml

@@ -84,3 +84,35 @@ jobs:
             -Dwith-tests=true
       - name: Run distribution tests
         run: meson dist -C build
+
+  build-doxygen-docs:
+    name: Build Doxygen Docs
+    runs-on: macos-latest
+    timeout-minutes: 12
+    env:
+      HOMEBREW_NO_INSTALL_CLEANUP: 1
+      HOMEBREW_NO_AUTO_UPDATE: 1
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - name: Install dependencies
+        run: |
+          brew update
+          brew upgrade
+          brew install \
+            bstring \
+            doxygen \
+            iniparser \
+            meson
+      - name: Configure
+        run: |
+          meson setup build \
+            -Dbuildtype=debug \
+            -Dwith-docs=developer \
+            -Dwith-doxygen-strict=true \
+            -Dwith-homebrew=true
+      - name: Upload Meson log on failure
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: meson-log
+          path: build/meson-logs/meson-log.txt

CONTRIBUTING.md

@@ -175,7 +175,6 @@ You can also use the `./contrib/scripts/codefmt.sh` convenience script to the sa
   - Variable and function names should be in snake_case
   - Lists of symbols, files etc. should be sorted in alphabetic order, unless a constraint dictates otherwise
   - One variable declaration and definition per line
-  - Code documentation comments should be in kernel-doc format
   - Alphanumeric symbols in optarg should be in alphabetical order, with unary options first and parameter options second
 
 Ex.
@@ -219,6 +218,37 @@ Ex.
  */
 ```
 
+- Code documentation comments
+  - Use *Qt style* comments for documenting functions, parameters, return values, structs, enums, and macros
+  - Use `/*! ... */` to indicate multi-line comments
+  - Use `/*!< ... */` to indicate single-line comments
+  - Use a *@* prefix for [commanded tags](https://www.doxygen.nl/manual/commands.html) such as `@param` and `@returns`
+  - A multi-line function documentation comment should have a `@brief` description first,
+    followed by a blank line, followed by a more elaborate description if needed,
+    followed by `@param` and `@returns` value documentation
+  - Indicate input/output status for `@param` with \[in\],[\out\], and \[[in,out]\] tags
+  - Use Markdown for rich formatting, for instance for numbered and bulleted lists
+
+Ex.
+
+```C
+/*!
+ * @brief Copy a string from a UCS2 src to a unix char * destination, allocating a buffer
+ *
+ * @param ch destination character set
+ * @param src source UCS2 string
+ * @param dest always set at least to NULL
+ * @param destlen maximum length of destination buffer
+ *
+ * @returns The number of bytes occupied by the string in the destination
+ */
+size_t ucs2_to_charset(charset_t ch, const ucs2_t *src, char *dest,
+                       size_t destlen)
+{
+    ...
+}
+```
+
 - Padding and alignment
   - Pointer and reference operators (*, &, or ^) should be aligned to the variable name
   - One space padding after comma

bin/getzones/getzones.c

@@ -282,9 +282,11 @@ void do_atp_lookup(struct sockaddr_at *saddr, uint8_t lookup_type,
 }
 
 
-/*
- * n:   number of zones in this packet
- * buf: zone length/name pairs
+/*!
+ * @brief Print zones from a getzone reply
+ * @param n        number of zones in this packet
+ * @param buf      zone length/name pairs
+ * @param charset  charset to convert zone names from
  */
 static void print_zones(short n, const char *buf, charset_t charset)
 {

bin/nad/nad.h

@@ -70,7 +70,7 @@ extern cnid_t cnid_for_paths_parent(const afpvol_t *vol, const char *path,
                                     cnid_t *did);
 extern char *utompath(const struct vol *, const char *);
 extern int convert_dots_encoding(const afpvol_t *svol, const afpvol_t *dvol,
-                                 char *path, size_t buflen);
+                                 char *path);
 
 typedef struct {
     char *p_end;/* pointer to NULL at end of path */

bin/nad/nad_cp.c

@@ -502,7 +502,7 @@ static int copy(const char *path,
 
     /* Convert basename to appropriate volume encoding */
     if (dvolume.vol->v_path
-            && (convert_dots_encoding(&svolume, &dvolume, to.p_path, MAXPATHLEN)) == -1) {
+            && (convert_dots_encoding(&svolume, &dvolume, to.p_path)) == -1) {
         SLOG("Error converting name for %s", to.p_path);
         badcp = rval = 1;
         return -1;

bin/nad/nad_util.c

@@ -92,10 +92,11 @@ void _log(enum logtype lt, char *fmt, ...)
 }
 
 /*!
- * Load volinfo and initialize struct vol
+ * @brief Load volinfo and initialize struct vol
  *
- * @param path   (r)  path to evaluate
- * @param vol    (rw) structure to initialize
+ * @param[in] obj        AFPObj of the current connection
+ * @param[in] path       path to evaluate
+ * @param[in,out] vol    structure to initialize
  *
  * @returns 0 on success, exits on error
  */
@@ -191,21 +192,20 @@ char *utompath(const struct vol *vol, const char *upath)
 
 
 /*!
- * Convert dot encoding of basename _in place_
+ * @brief Convert dot encoding of basename _in place_
  *
  * path arg can be "[/][dir/ | ...]filename". It will be converted in place
  * possible encoding ".file" as ":2efile" which means the result will be
  * longer then the original which means provide a big enough buffer.
  *
- * @param svol   (r)  source volume
- * @param dvol   (r)  destinatio volume
- * @param path   (rw) path to convert _in place_
- * @param buflen (r)  size of path buffer (max strlen == buflen - 1)
+ * @param[in] svol       source volume
+ * @param[in] dvol       destination volume
+ * @param[in,out] path   path to convert _in place_
  *
- * @returns 0 on sucess, -1 on error
+ * @returns 0 on success, -1 on error
  */
 int convert_dots_encoding(const afpvol_t *svol, const afpvol_t *dvol,
-                          char *path, size_t buflen _U_)
+                          char *path)
 {
     static charset_t from = (charset_t) -1;
     static char buf[MAXPATHLEN + 2];
@@ -243,7 +243,7 @@ int convert_dots_encoding(const afpvol_t *svol, const afpvol_t *dvol,
 }
 
 /*!
- * Resolves CNID of a given paths parent directory
+ * @brief Resolves CNID of a given paths parent directory
  *
  * path might be:
  * (a) relative:
@@ -254,9 +254,9 @@ int convert_dots_encoding(const afpvol_t *svol, const afpvol_t *dvol,
  * path MUST be pointing inside vol, this is usually the case as vol has been build from
  * path using loadvolinfo and friends.
  *
- * @param vol  (r) pointer to afpvol_t
- * @param path (r) path, see above
- * @param did  (rw) parent CNID of returned CNID
+ * @param[in] vol      pointer to afpvol_t
+ * @param[in] path     path, see above
+ * @param[in,out] did  parent CNID of returned CNID
  *
  * @returns CNID of path
  */

doc/Doxyfile.in

@@ -949,7 +949,7 @@ WARN_LAYOUT_FILE       = YES
 # Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT.
 # The default value is: NO.
 
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = @WARN_AS_ERROR@
 
 # The WARN_FORMAT tag determines the format of the warning messages that Doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
@@ -1062,7 +1062,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */build/*
+EXCLUDE_PATTERNS       = */build/* */dummy.c */meson_config.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -2401,15 +2401,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2442,7 +2442,36 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = \
+    HAVE_ACLS=1 \
+    HAVE_AVAHI=1 \
+    HAVE_CUPS=1 \
+    HAVE_DBUS_GLIB=1 \
+    HAVE_LDAP=1 \
+    HAVE_LIBQUOTA=1 \
+    HAVE_MDNS=1 \
+    HAVE_POSIX_ACLS=1 \
+    HAVE_SPLICE=1 \
+    TCPWRAP=1 \
+    USE_CRACKLIB=1 \
+    WITH_DTRACE=1 \
+    WITH_RECVFILE=1 \
+    WITH_SENDFILE=1 \
+    WITH_SPOTLIGHT=1 \
+    __attribute__(x)= \
+    _U_= \
+    restrict= \
+    VFS_FUNC_ARGS_CHOWN="const struct vol *vol, const char *path, uid_t uid, gid_t gid" \
+    VFS_FUNC_ARGS_COPYFILE="const struct vol *vol, int sfd, const char *src, const char *dst" \
+    VFS_FUNC_ARGS_DELETEFILE="const struct vol *vol, int dirfd, const char *file" \
+    VFS_FUNC_ARGS_EA_GETCONTENT="const struct vol * restrict vol, char * restrict rbuf, size_t * restrict rbuflen, const char * restrict uname, int oflag, const char * restrict attruname, int maxreply, int fd" \
+    VFS_FUNC_ARGS_EA_GETSIZE="const struct vol * restrict vol, char * restrict rbuf, size_t * restrict rbuflen, const char * restrict uname, int oflag, const char * restrict attruname, int fd" \
+    VFS_FUNC_ARGS_EA_LIST="const struct vol * restrict vol, char * restrict attrnamebuf, size_t * restrict buflen, const char * restrict uname, int oflag, int fd" \
+    VFS_FUNC_ARGS_EA_REMOVE="const struct vol * restrict vol, const char * restrict uname, const char * restrict attruname, int oflag, int fd" \
+    VFS_FUNC_ARGS_EA_SET="const struct vol * restrict vol, const char * restrict uname, const char * restrict attruname, const char * restrict ibuf, size_t attrsize, int oflag, int fd" \
+    VFS_FUNC_ARGS_RENAMEFILE="const struct vol *vol, int dirfd, const char *src, const char *dst" \
+    VFS_FUNC_ARGS_SETDIRUNIXMODE="const struct vol *vol, const char *name, mode_t mode, struct stat *st" \
+    VFS_FUNC_ARGS_SETFILEMODE="const struct vol *vol, const char *name, mode_t mode, struct stat *st" \
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doc/developer/dircache.md

@@ -44,9 +44,9 @@ graph TB
     FS --> ARC
     ARC --> DISK
 
-    style PC fill:#ffcccc
-    style DC fill:#ccffcc
-    style ARC fill:#ffcccc
+    style PC fill:\#ffcccc
+    style DC fill:\#ccffcc
+    style ARC fill:\#ffcccc
 ```
 
 Each cache layer uses an **LRU (Least Recently Used)** algorithm to decide what to keep in memory
@@ -201,9 +201,9 @@ flowchart TD
     Add_Cache --> Return[Return to client]
     Use_Cached --> Return
 
-    style DC_Check fill:#e6f3ff
-    style CNID_Query fill:#ffe6e6
-    style FS_Check fill:#ffffe6
+    style DC_Check fill:\#e6f3ff
+    style CNID_Query fill:\#ffe6e6
+    style FS_Check fill:\#ffffe6
 ```
 
 ### The Precedence Hierarchy
@@ -362,10 +362,10 @@ graph LR
     M3 --> R3[Reduced read IOPS]
     M4 --> R4[Higher hit ratio]
 
-    style R1 fill:#e6f3ff
-    style R2 fill:#e6f3ff
-    style R3 fill:#e6f3ff
-    style R4 fill:#e6f3ff
+    style R1 fill:\#e6f3ff
+    style R2 fill:\#e6f3ff
+    style R3 fill:\#e6f3ff
+    style R4 fill:\#e6f3ff
 ```
 
 ### Sample Statistics

doc/meson.build

@@ -37,6 +37,12 @@ if build_dev_docs and doxygen.found()
     doxyfile_conf.set('ABS_TOP_SRCDIR', meson.project_source_root())
     doxyfile_conf.set('OUTPUT_DIR', meson.current_build_dir())
 
+    if get_option('with-doxygen-strict')
+        doxyfile_conf.set('WARN_AS_ERROR', 'YES')
+    else
+        doxyfile_conf.set('WARN_AS_ERROR', 'NO')
+    endif
+
     doxyfile = configure_file(input: 'Doxyfile.in', output: 'Doxyfile', configuration: doxyfile_conf)
 
     run_command(doxygen, doxyfile, check: true)