Replace an erroneous assert in diagnose_files() with a doxygen comment

The `Seq **corrupt` argument of the diagnose_files() function is
an out parameter, a place to store the sequence of detected
corrupted files. It can be NULL if the caller only wants to get
the number of such corrupted files, but otherwise it doesn't have
to be initialized. In fact, it should not be initialized in most
cases to not confuse the "used but not initialized" compiler
check.

Instead of `assert(corrupt == NULL | *corrupt == NULL)`, let's
just decribe the meaning of parameters and return value in a
doxygen comment.

Also mark the first parameter (`Seq *files`) as `const`, because
the sequence is not modified by the function.

(cherry picked from commit 41d6e3c)

cf-check/diagnose.c

@@ -12,7 +12,7 @@ int diagnose_main(ARG_UNUSED int argc, ARG_UNUSED const char *const *const argv)
 }
 
 size_t diagnose_files(
-    ARG_UNUSED Seq *filenames, ARG_UNUSED Seq **corrupt, bool foreground)
+    ARG_UNUSED const Seq *filenames, ARG_UNUSED Seq **corrupt, bool foreground)
 {
     Log(LOG_LEVEL_INFO,
         "database diagnosis not available on this platform/build");
@@ -275,9 +275,15 @@ static int fork_and_diagnose(const char *path)
     return CF_CHECK_OK;
 }
 
-size_t diagnose_files(Seq *filenames, Seq **corrupt, bool foreground)
+/**
+ * @param[in]  filenames  DB files to diagnose/check
+ * @param[out] corrupt    place to store the resulting sequence of corrupted files
+ *                        or %NULL (to only get the number of corrupted files)
+ * @param[in]  foreground whether to run in foreground or fork (safer)
+ * @return                the number of the corrupted files
+ */
+size_t diagnose_files(const Seq *filenames, Seq **corrupt, bool foreground)
 {
-    assert(corrupt == NULL || *corrupt == NULL);
     size_t corruptions = 0;
     const size_t length = SeqLength(filenames);
     for (int i = 0; i < length; ++i)

cf-check/diagnose.h

@@ -74,7 +74,7 @@ typedef enum {
 
 int lmdb_errno_to_cf_check_code(int r);
 int signal_to_cf_check_code(int sig);
-size_t diagnose_files(Seq *filenames, Seq **corrupt, bool foreground);
+size_t diagnose_files(const Seq *filenames, Seq **corrupt, bool foreground);
 int diagnose_main(int argc, const char *const *argv);
 
 #endif