QDoc: Move catch_generators under src

QDoc employs a support library, "catch_generators", to
provide custom support for the data-generation that certain tests use or
might want to use when using the Catch2 testing framework, which QDoc
uses for some of its tests.

"catch_generators" was currently kept under "tests/auto/qdoc" and its
headers were included and used directly by related tests by relative
paths.

Due to a certain restructuring that is happening in QDoc, with one of
the goals, among others, being to increase the locality of QDoc-related
code under "src/qdoc", the "catch_generators" support library is now
moved under "src/qdoc".

To allow code that depended on it to keep their usages without requiring
the addition of some relative paths from the "tests" directory to the
"src" directory, a library target, "Qt::QDocCatchGeneratorsPrivate" was
created for it.

The target can be linked-to to gain access to the
previously-directly-used headers, with include path
"catch_generators/.*".

To allow for this specific include path to work, the internal directory
structure for "catch_generators" was slightly modified with the
addition of some intermediate directories in between its root and the
library headers.

The root "CMakeLists.txt" file for the QDoc project was modified to add
the moved "catch_generators" as a subdirectory, to include it in the
build process.

"catch_generators" contains its own test code under the subdirectory
"tests".
Previously the test target in "tests" included the relevant headers from
the library by use of relative paths to its sources.
Now that the library is exported as a target, the "CMakeLists.txt" file
under "tests" was modified to rely on linking to the library itself to
obtain access to the required headers.

Similarly, targets under "tests/auto/qdoc" that used the dependency now
link to it instead. Hence, their "CMakeLists.txt" files were modified to
avoid using the dependency as an include directory and instead use
"Qt::QDocCatcGeneratorsPrivate" as a library.

The inclusions of the "catch_generators" headers in
relevant sources was modified to respect the new "catch_generators/.*"
path.

Additionally, "catch_generators" exposed a top level header,
"qdoc_catch_generators.h", including certain headers in the library that
were expected to be commonly used by tests, so that the consumers did
not have to include multiple headers when using various common generators.

The header was removed in favor of including the library headers
themselves now that they have a well-defined root provided by the
exposed target.

Sources that included the header were modified to include only their
relevant headers from "catch_generators", respecting the additional
granularity.

Due to the Qt Project CI performing discovery of tests by configuring
only the "tests" directory of the module; the moved "catch_generators",
which contained its own testing code, will now escape the automated
testing in CI for its own tests, as the relevant target does not reside
under the "tests" directory of the repository.

To avoid this issue, the "CMakeLists.txt" file under "tests/auto/qdoc",
was modified to `include` the "CMakeLists.txt" file that describes
"catch_generators"' test target, so as to "mirror" the test under the
"tests" directory.

To support working when included, the "CMakeLists.txt" file that
describes "catch_generators"' test target was modified to refer to any
relevant relative path by prefixing the value of
`CMAKE_CURRENT_LIST_DIR`, so that the relative paths would not be
incorrectly resolved when using `include`.

Due to this "mirroring", the relevant test target would be configured
twice when the whole repository was configured, resulting in an error.
To ensure that this is not the case, the `include` directive was hidden
behind `QT_BUILD_STANADALONE_TESTS`, which is not set during a general
configuration of the repository but is set when CI performs
test-discovery on the "tests" directory.

Similarly, the "tests" directory of a repository is configured only when
`QT_BUILD_TESTS` is `ON`, which further ensures that the required
dependencies, such as `Qt::Test`, will be found before the directory is
configured.
By having moved the test declaration outside of the `tests` directory,
the test will always be configured, failing to find its dependencies
when this happens.
To avoid the issue, the `add_subdirectory(tests)` directive in
`src/qdoc/catch_generators/CMakeLists.txt` was conditioned over `QT_BUILD_TESTS`.

Certain files that were missing an license header were enhanced with it,
as the lack of an header will now be an issue outside the "tests" directory.

Change-Id: I0bca477b7da75c121c24b8528fc9defa26a6123e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

1 files changed, 853 insertions, 0 deletions

diff --git a/src/qdoc/catch_generators/src/catch_generators/generators/path_generator.h b/src/qdoc/catch_generators/src/catch_generators/generators/path_generator.h
new file mode 100644
index 000000000..875502e49
--- /dev/null
+++ b/src/qdoc/catch_generators/src/catch_generators/generators/path_generator.h
@@ -0,0 +1,853 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
+
+// TODO: Change the include paths to implicitly consider
+// `catch_generators` a root directory and change the CMakeLists.txt
+// file to make this possible.
+
+#include "../namespaces.h"
+#include "qchar_generator.h"
+#include "qstring_generator.h"
+#include "../utilities/semantics/move_into_vector.h"
+#include "../utilities/semantics/generator_handler.h"
+
+#if defined(Q_OS_WINDOWS)
+
+    #include "combinators/cycle_generator.h"
+
+#endif
+
+#include <catch/catch.hpp>
+
+#include <random>
+
+#include <QChar>
+#include <QString>
+#include <QStringList>
+#include <QRegularExpression>
+
+#if defined(Q_OS_WINDOWS)
+
+    #include <QStorageInfo>
+
+#endif
+
+namespace QDOC_CATCH_GENERATORS_ROOT_NAMESPACE {
+
+
+    struct PathGeneratorConfiguration {
+        double multi_device_path_probability{0.5};
+        double absolute_path_probability{0.5};
+        double directory_path_probability{0.5};
+        double has_trailing_separator_probability{0.5};
+        std::size_t minimum_components_amount{1};
+        std::size_t maximum_components_amount{10};
+
+        PathGeneratorConfiguration& set_multi_device_path_probability(double amount) {
+            multi_device_path_probability = amount;
+            return *this;
+        }
+
+        PathGeneratorConfiguration& set_absolute_path_probability(double amount) {
+            absolute_path_probability = amount;
+            return *this;
+        }
+
+        PathGeneratorConfiguration& set_directory_path_probability(double amount) {
+            directory_path_probability = amount;
+            return *this;
+        }
+
+        PathGeneratorConfiguration& set_has_trailing_separator_probability(double amount) {
+            has_trailing_separator_probability = amount;
+            return *this;
+        }
+
+        PathGeneratorConfiguration& set_minimum_components_amount(std::size_t amount) {
+            minimum_components_amount = amount;
+            return *this;
+        }
+
+        PathGeneratorConfiguration& set_maximum_components_amount(std::size_t amount) {
+            maximum_components_amount = amount;
+            return *this;
+        }
+    };
+
+    /*!
+     * \class PathGeneratorConfiguration
+     * \brief Defines some parameters to customize the generation of
+     * paths by a PathGenerator.
+     */
+
+    /*!
+     * \variable PathGeneratorConfiguration::multi_device_path_probability
+     *
+     * Every path produced by a PathGenerator configured with a
+     * mutli_device_path_probability of n has a probability of n to be
+     * \e {Multi-Device} and a probability of 1.0 - n to not be \a
+     * {Multi-Device}.
+     *
+     * multi_device_path_probability should be a value in the range [0.0,
+     * 1.0].
+     */
+
+    /*!
+     * \variable PathGeneratorConfiguration::absolute_path_probability
+     *
+     * Every path produced by a PathGenerator configured with an
+     * absolute_path_probability of n has a probability of n to be \e
+     * {Absolute} and a probability of 1.0 - n to be \e {Relative}.
+     *
+     * absolute_path_probability should be a value in the range [0.0,
+     * 1.0].
+     */
+
+    /*!
+     * \variable PathGeneratorConfiguration::directory_path_probability
+     *
+     * Every path produced by a PathGenerator configured with a
+     * directory_path_probability of n has a probability of n to be \e
+     * {To a Directory} and a probability of 1.0 - n to be \e {To a
+     * File}.
+     *
+     * directory_path_probability should be a value in the range [0.0,
+     * 1.0].
+     */
+
+    /*!
+     * \variable PathGeneratorConfiguration::has_trailing_separator_probability
+     *
+     * Every path produced by a PathGenerator configured with an
+     * has_trailing_separator_probability of n has a probability of n
+     * to \e {Have a Trailing Separator} and a probability of 1.0 - n
+     * to not \e {Have a Trailing Separator}, when this is applicable.
+     *
+     * has_trailing_separator_probability should be a value in the
+     * range [0.0, 1.0].
+     */
+
+    /*!
+     * \variable PathGeneratorConfiguration::minimum_components_amount
+     *
+     * Every path produced by a PathGenerator configured with a
+     * minimum_components_amount of n will be the concatenation of at
+     * least n non \e {device}, non \e {root}, non \e {separator}
+     * components.
+     *
+     * minimum_components_amount should be greater than zero and less
+     * than maximum_components_amount.
+     */
+
+    /*!
+     * \variable PathGeneratorConfiguration::maximum_components_amount
+     *
+     * Every path produced by a PathGenerator configured with a
+     * maximum_components_amount of n will be the concatenation of at
+     * most n non \e {device}, non \e {root}, non \e {separator} components.
+     *
+     * maximum_components_amount should be greater than or equal to
+     * minimum_components_amount.
+     */
+
+
+    namespace QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE {
+
+        class PathGenerator : public Catch::Generators::IGenerator<QString> {
+        public:
+            PathGenerator(
+                Catch::Generators::GeneratorWrapper<QString>&& device_component_generator,
+                Catch::Generators::GeneratorWrapper<QString>&& root_component_generator,
+                Catch::Generators::GeneratorWrapper<QString>&& directory_component_generator,
+                Catch::Generators::GeneratorWrapper<QString>&& filename_component_generator,
+                Catch::Generators::GeneratorWrapper<QString>&& separator_component_generator,
+                PathGeneratorConfiguration configuration = PathGeneratorConfiguration{}
+            ) : device_component_generator{QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::handler(std::move(device_component_generator))},
+                root_component_generator{QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::handler(std::move(root_component_generator))},
+                directory_component_generator{QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::handler(std::move(directory_component_generator))},
+                filename_component_generator{QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::handler(std::move(filename_component_generator))},
+                separator_component_generator{QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::handler(std::move(separator_component_generator))},
+                random_engine{std::random_device{}()},
+                components_amount_distribution{configuration.minimum_components_amount, configuration.maximum_components_amount},
+                is_multi_device_distribution{configuration.multi_device_path_probability},
+                is_absolute_path_distribution{configuration.absolute_path_probability},
+                is_directory_path_distribution{configuration.directory_path_probability},
+                has_trailing_separator{configuration.has_trailing_separator_probability},
+                current_path{}
+            {
+                assert(configuration.minimum_components_amount > 0);
+                assert(configuration.minimum_components_amount <= configuration.maximum_components_amount);
+
+                if (!next())
+                    Catch::throw_exception("Not enough values to initialize the first string");
+            }
+
+            QString const& get() const override { return current_path; }
+
+            bool next() override {
+                std::size_t components_amount{components_amount_distribution(random_engine)};
+
+                current_path = "";
+
+                // REMARK: As per our specification of a path, we
+                // do not count device components, and separators,
+                // when considering the amount of components in a
+                // path.
+                // This is a tradeoff that is not necessarily
+                // precise.
+                // Counting those kinds of components, on one
+                // hand, would allow a device component to stands
+                // on its own as a path, for example "C:", which
+                // might actually be correct in some path format.
+                // On the other hand, counting those kinds of
+                // components makes the construction of paths for
+                // our model much more complex with regards, for
+                // example, to the amount of component.
+                //
+                // Counting device components, since they can
+                // appear both in relative and absolute paths,
+                // makes the minimum amount of components
+                // different for different kinds of paths.
+                //
+                // Since absolute paths always require a root
+                // component, the minimum amount of components for
+                // a multi-device absolute path is 2.
+                //
+                // But an absolute path that is not multi-device
+                // would only require one minimum component.
+                //
+                // Similarly, problems arise with the existence of
+                // Windows' relative multi-device path, which
+                // require a leading separator component after a
+                // device component.
+                //
+                // This problem mostly comes from our model
+                // simplifying the definition of paths quite a bit
+                // into binary-forms.
+                // This simplifies the code and its structure,
+                // sacrificing some precision.
+                // The lost precision is almost none for POSIX
+                // based paths, but is graver for DOS paths, since
+                // they have a more complex specification.
+                //
+                // Currently, we expect that the paths that QDoc
+                // will encounter will mostly be in POSIX-like
+                // forms, even on Windows, and aim to support
+                // that, such that the simplification of code is
+                // considered a better tradeoff compared to the
+                // loss of precision.
+                //
+                // If this changes, the model should be changed to
+                // pursue a Windows-first modeling, moving the
+                // categorization of paths from the current binary
+                // model to the absolute, drive-relative and
+                // relative triptych that Windows uses.
+                // This more complex model should be able to
+                // completely describe posix paths too, making it
+                // a superior choice as long as the complexity is
+                // warranted.
+                //
+                // Do note that the model similarly can become
+                // inconsistent when used to generate format of
+                // paths such as the one used in some resource
+                // systems.
+                // Those are considered out-of-scope for our needs
+                // and were not taken into account when developing
+                // this generator.
+                if (is_multi_device_distribution(random_engine)) {
+                    if (!device_component_generator.next()) return false;
+                    current_path += device_component_generator.get();
+                }
+
+                // REMARK: Similarly to not counting other form of
+                // components, we do not count root components
+                // towards the amounts of components that the path
+                // has to simplify the code.
+                // To support the "special" root path on, for
+                // example, posix systems, we require a more
+                // complex branching logic that changes based on
+                // the path being absolute or not.
+                //
+                // We don't expect root to be a particularly
+                // useful path for QDoc purposes and expect to not
+                // have to consider it for our tests.
+                // If consideration for it become required, it is
+                // possible to test it directly in the affected
+                // systemss as a special case.
+                //
+                // If most systems are affected by the handling of
+                // a root path, then the model should be slightly
+                // changed to accommodate its generation.
+                if (is_absolute_path_distribution(random_engine)) {
+                    if (!root_component_generator.next()) return false;
+
+                    current_path += root_component_generator.get();
+                }
+
+                std::size_t prefix_components_amount{std::max(std::size_t{1}, components_amount) - 1};
+                while (prefix_components_amount > 0) {
+                    if (!directory_component_generator.next()) return false;
+                    if (!separator_component_generator.next()) return false;
+
+                    current_path += directory_component_generator.get() + separator_component_generator.get();
+                    --prefix_components_amount;
+                }
+
+                if (is_directory_path_distribution(random_engine)) {
+                    if (!directory_component_generator.next()) return false;
+                    current_path += directory_component_generator.get();
+
+                    if (has_trailing_separator(random_engine)) {
+                        if (!separator_component_generator.next()) return false;
+                        current_path += separator_component_generator.get();
+                    }
+                } else {
+                    if (!filename_component_generator.next()) return false;
+                    current_path += filename_component_generator.get();
+                }
+
+                return true;
+            }
+
+        private:
+            Catch::Generators::GeneratorWrapper<QString> device_component_generator;
+            Catch::Generators::GeneratorWrapper<QString> root_component_generator;
+            Catch::Generators::GeneratorWrapper<QString> directory_component_generator;
+            Catch::Generators::GeneratorWrapper<QString> filename_component_generator;
+            Catch::Generators::GeneratorWrapper<QString> separator_component_generator;
+
+            std::mt19937 random_engine;
+            std::uniform_int_distribution<std::size_t> components_amount_distribution;
+            std::bernoulli_distribution is_multi_device_distribution;
+            std::bernoulli_distribution is_absolute_path_distribution;
+            std::bernoulli_distribution is_directory_path_distribution;
+            std::bernoulli_distribution has_trailing_separator;
+
+            QString current_path;
+        };
+
+    } // end QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE
+
+/*!
+    * Returns a generator that produces QStrings that represent a
+    * path in a filesystem.
+    *
+    * A path is formed by the following components, loosely based
+    * on the abstraction that is used by std::filesystem::path:
+    *
+    * \list
+    * \li \b {device}:
+    *     Represents the device on the filesystem that
+    *     the path should be considered in terms of.
+    *     This is an optional components that is sometimes
+    *     present on multi-device systems, such as Windows, to
+    *     distinguish which device the path refers to.
+    *     When present, it always appears before any other
+    *     component.
+    * \li \b {root}:
+    *     A special sequence that marks the path as absolute.
+    *     This is an optional component that is present, always,
+    *     in absolute paths.
+    * \li \b {directory}:
+    *     A component that represents a directory on the
+    *     filesystem that the path "passes-trough".
+    *     Zero or more of this components can be present in the
+    *     path.
+    *     A path pointing to a directory on the filesystem that
+    *     is not \e {root} always ends with a component of this
+    *     type.
+    * \li \b {filename}:
+    *     A component that represents a file on the
+    *     filesystem.
+    *     When this component is present, it is present only once
+    *     and always as the last component of the path.
+    *     A path that has such a component is a path that points
+    *     to a file on the filesystem.
+    *     For some path formats, there is no difference in the
+    *     format of a \e {filename} and a \e {directory}.
+    * \li \b {separator}:
+    *     A component that is interleaved between other types of
+    *     components to separate them so that they are
+    *     recognizable.
+    *     A path that points to a directory on the filesystem may
+    *     sometimes have a \e {separator} at the end, after the
+    *     ending \e {directory} component.
+    * \endlist
+    *
+    * Each component is representable as a string and a path is a
+    * concatenation of the string representation of some
+    * components, with the following rules:
+    *
+    * \list
+    * \li There is at most one \e {device} component.
+    * \li If a \e {device} component is present it always
+    * precedes all other components.
+    * \li There is at most one \e {root} component.
+    * \li If a \e {root} component is present it:
+    *     \list
+    *     \li Succeeds the \e {device} component if it is present.
+    *     \li Precedes every other components if the \e {device}
+    *     component is not present.
+    *     \endlist
+    * \li There are zero or more \e {directory} component.
+    * \li There is at most one \e {filename} component.
+    * \li If a \e {filename} component is present it always
+    * succeeds all other components.
+    * \li Between any two successive \e {directory} components
+    * there is a \e {separator} component.
+    * \li Between each successive \e {directory} and \e
+    * {filename} component there is a \e {separator} component.
+    * \li If the last component is a \e {directory} component it
+    * can be optionally followed by a \e {separator} component.
+    * \li At least one component that is not a \e {device}, a \e
+    * {root} or \e {separator} component is present.
+    * \endlist
+    *
+    * For example, if "C:" is a \e {device} component, "\\" is a
+    * \e {root} component, "\\" is a \e {separator} component,
+    * "directory" is a \e {directory} component and "filename" is
+    * a \e {filename} component, the following are all paths:
+    *
+    * "C:\\directory", "C:\\directory\\directory", "C:filename",
+    * "directory\\directory\\", "\\directory\\filename", "filename".
+    *
+    * While the following aren't:
+    *
+    * "C:", "C:\\", "directory\\C:", "foo", "C:filename\\",
+    * "filename\\directory\\filename", "filename\\filename",
+    * "directorydirectory"."
+    *
+    * The format of different components type can be the same.
+    * For example, the \e {root} and \e {separator} component in
+    * the above example.
+    * For the purpose of generation, we do not care about the
+    * format itself and consider a component of a certain type
+    * depending only on how it is generated/where it is generated
+    * from.
+    *
+    * For example, if every component is formatted as the string
+    * "a", the string "aaa" could be a generated path.
+    * By the string alone, it is not possible to simply discern
+    * which components form it, but it would be possible to
+    * generate it if the first "a" is a \a {device} component,
+    * the second "a" is a \e {root} component and the third "a"
+    * is a \e {directory} or \e {filename} component.
+    *
+    * A path, is further said to have some properties, pairs of
+    * which are exclusive to each other.
+    *
+    * A path is said to be:
+    *
+    * \list
+    * \li \b {Multi-Device}:
+    *     When it contains a \e {device} component.
+    * \li \b {Absolute}:
+    *     When it contains a \e {root} component.
+    *     If the path is \e {Absolute} it is not \e {Relative}.
+    * \li \b {Relative}:
+    *     When it does not contain a \e {root} component.
+    *     If the path is \e {Relative} it is not \e {Absolute}.
+    * \li \b {To a Directory}:
+    *     When its last component is a \e {directory} component
+    *     or a \e {directory} component followed by a \e
+    *     {separator} component.
+    *     If the path is \e {To a Directory} it is not \e {To a
+    *     File}.
+    * \li \b {To a File}:
+    *     When its last component is a \e {filename}.
+    *     If the path is \e {To a File} it is not \e {To a
+    *     Directory}.
+    * \endlist
+    *
+    * All path are \e {Relative/Absolute}, \e {To a
+    * Directory/To a File} and \e {Multi-Device} or not.
+    *
+    * Furthermore, a path that is \e {To a Directory} and whose
+    * last component is a \e {separator} component is said to \e
+    * {Have a Trailing Separator}.
+    */
+    inline Catch::Generators::GeneratorWrapper<QString> path(
+        Catch::Generators::GeneratorWrapper<QString>&& device_generator,
+        Catch::Generators::GeneratorWrapper<QString>&& root_component_generator,
+        Catch::Generators::GeneratorWrapper<QString>&& directory_generator,
+        Catch::Generators::GeneratorWrapper<QString>&& filename_generator,
+        Catch::Generators::GeneratorWrapper<QString>&& separator_generator,
+        PathGeneratorConfiguration configuration = PathGeneratorConfiguration{}
+    ) {
+        return Catch::Generators::GeneratorWrapper<QString>(
+            std::unique_ptr<Catch::Generators::IGenerator<QString>>(
+                new QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::PathGenerator(std::move(device_generator), std::move(root_component_generator), std::move(directory_generator), std::move(filename_generator), std::move(separator_generator), configuration)
+            )
+        );
+    }
+
+    namespace QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE {
+
+        // REMARK: We need a bounded length for the generation of path
+        // components as strings.
+        // We trivially do not want components to be the empty string,
+        // such that we have a minimum length of 1, but the maximum
+        // length is more malleable.
+        // We don't want components that are too long to avoid
+        // incurring in a big performance overhead, as we may generate
+        // many of them.
+        // At the same time, we want some freedom in having diffent
+        // length components.
+        // The value that was chosen is based on the general value for
+        // POSIX's NAME_MAX, which seems to tend to be 14 on many systems.
+        // We see this value as a small enough but not too much value
+        // that further brings with itself a relation to paths,
+        // increasing our portability even if it is out of scope, as
+        // almost no modern respects NAME_MAX.
+        // We don't use POSIX's NAME_MAX directly as it may not be available
+        // on all systems.
+        inline static constexpr std::size_t minimum_component_length{1};
+        inline static constexpr std::size_t maximum_component_length{14};
+
+        /*!
+         * Returns a generator that generates strings that are
+         * suitable to be used as a root component in POSIX paths.
+         *
+         * As per
+         * \l {https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_02},
+         * this is any sequence of slash characters that is not of
+         * length 2.
+         */
+        inline Catch::Generators::GeneratorWrapper<QString> posix_root() {
+            return uniformly_valued_oneof(
+                QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::move_into_vector(
+                    string(character('/', '/'), 1, 1),
+                    string(character('/', '/'), 3, maximum_component_length)
+                ),
+                std::vector{1, maximum_component_length - 3}
+            );
+        }
+
+        /*!
+         * Returns a generator that generates strings that are
+         * suitable to be used as directory components in POSIX paths
+         * and that use an alphabet that should generally be supported
+         * by other systems.
+         *
+         * Components of this kind use the \l
+         * {https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282}{Portable Filename Character Set}.
+         */
+        inline Catch::Generators::GeneratorWrapper<QString> portable_posix_directory_name() {
+            return string(
+                QDOC_CATCH_GENERATORS_QCHAR_ALPHABETS_NAMESPACE::portable_posix_filename(),
+                minimum_component_length, maximum_component_length
+            );
+        }
+
+        /*!
+         * Returns a generator that generates strings that are
+         * suitable to be used as filenames in POSIX paths and that
+         * use an alphabet that should generally be supported by
+         * other systems.
+         *
+         * Filenames of this kind use the \l
+         * {https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282}{Portable Filename Character Set}.
+         */
+        inline Catch::Generators::GeneratorWrapper<QString> portable_posix_filename() {
+            // REMARK: "." and ".." always represent directories so we
+            // avoid generating them. Other than this, there is no
+            // difference between a file name and a directory name.
+            return filter([](auto& filename) { return filename != "." && filename != ".."; },  portable_posix_directory_name());
+        }
+
+        /*!
+         * Returns a generator that generates strings that can be used
+         * as POSIX compliant separators.
+         *
+         * As per \l
+         * {https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_271},
+         * a separator is a sequence of one or more slashes.
+         */
+        inline Catch::Generators::GeneratorWrapper<QString> posix_separator() {
+            return string(character('/', '/'), minimum_component_length, maximum_component_length);
+        }
+
+        /*!
+         * Returns a generator that generates strings that can be
+         * suitably used as logical drive names in Windows' paths.
+         *
+         * As per \l
+         * {https://docs.microsoft.com/en-us/dotnet/standard/io/file-path-formats#traditional-dos-paths}
+         * and \l
+         * {https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getlogicaldrives},
+         * they are composed of a single letter.
+         * Each generated string always follows the lettet with a
+         * colon, as it is specifically intended for path usages,
+         * where this is required.
+         *
+         * We use only uppercase letters for the drives names albeit,
+         * depending on case sensitivity, lowercase letter could be
+         * used.
+         */
+        inline Catch::Generators::GeneratorWrapper<QString> windows_logical_drives() {
+            // REMARK: If a Windows path is generated on Windows
+            // itself, we expect that it may be used to interact with
+            // the filesystem, similar to how we expect a POSIX path
+            // to be used on Linux.
+            // For this reason, we only generate a specific drive, the one
+            // that contains the current working directory, so that we
+            // know it is an actually available drive and to contain the
+            // possible modifications to the filesystem to an easily
+            // foundable place.
+
+#if defined(Q_OS_WINDOWS)
+
+            auto root_device{QStorageInfo{QDir()}.rootPath().first(1) + ":"};
+
+            return cycle(Catch::Generators::value(std::move(root_device)));
+
+#else
+
+            return Catch::Generators::map(
+                [](QString letter){ return letter + ':';},
+                string(QDOC_CATCH_GENERATORS_QCHAR_ALPHABETS_NAMESPACE::ascii_uppercase(), 1, 1)
+            );
+
+#endif
+        }
+
+        /*!
+         * Returns a generator that generate strings that can be used
+         * as separators in Windows based paths.
+         *
+         * As per \l
+         * {https://docs.microsoft.com/en-us/dotnet/api/system.io.path.directoryseparatorchar?view=net-6.0}
+         * and \l
+         * {https://docs.microsoft.com/en-us/dotnet/standard/io/file-path-formats#canonicalize-separators},
+         * this is a sequence of one or more backward or forward slashes.
+         */
+        inline Catch::Generators::GeneratorWrapper<QString> windows_separator() {
+            return uniform_oneof(
+                QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::move_into_vector(
+                    string(character('\\', '\\'), minimum_component_length, maximum_component_length),
+                    string(character('/', '/'), minimum_component_length, maximum_component_length)
+                )
+            );
+        }
+
+    } // end QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE
+
+    /*!
+     * Returns a generator that generates strings representing
+     * POSIX compatible paths.
+     *
+     * The generated paths follows the format specified in \l
+     * {https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_271}.
+     *
+     * The optional length-requirements, such as PATH_MAX and
+     * NAME_MAX, are relaxed away as they are generally not
+     * respected by modern systems.
+     *
+     * It is possible to set the probability of obtaining a
+     * relative or absolute path through \a
+     * absolute_path_probability and the one of obtaining a path
+     * potentially pointing ot a directory or on a file through \a
+     * directory_path_probability.
+     */
+    inline Catch::Generators::GeneratorWrapper<QString> relaxed_portable_posix_path(double absolute_path_probability = 0.5, double directory_path_probability = 0.5) {
+        return path(
+            // POSIX path are never multi-device, so that we have
+            // provide an empty device component generator and set
+            // the probability for Multi-Device paths to zero.
+            string(character(), 0, 0),
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::posix_root(),
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::portable_posix_directory_name(),
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::portable_posix_filename(),
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::posix_separator(),
+            PathGeneratorConfiguration{}
+                .set_multi_device_path_probability(0.0)
+                .set_absolute_path_probability(absolute_path_probability)
+                .set_directory_path_probability(directory_path_probability)
+        );
+    }
+
+    /*!
+     * Returns a generator that produces strings that represents
+     * traditional DOS paths as defined in \l
+     * {https://docs.microsoft.com/en-us/dotnet/standard/io/file-path-formats#traditional-dos-paths}.
+     *
+     * The directory and filename components of a path generated
+     * in this way are, currently, restricted to use a portable
+     * character set as defined by POSIX.
+     *
+     * Do note that most paths themselves, will not be portable, on
+     * the whole, albeit they may be valid paths on other systems, as
+     * Windows uses a path system that is generally incompatible with
+     * other systems.
+     *
+     * Some possibly valid special path, such as a "C:" or "\"
+     * will never be generated.
+     */
+    inline Catch::Generators::GeneratorWrapper<QString> traditional_dos_path(
+        double absolute_path_probability = 0.5,
+        double directory_path_probability = 0.5,
+        double multi_device_path_probability = 0.5
+    ) {
+        return path(
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::windows_logical_drives(),
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::windows_separator(),
+            // REMAKR: Windows treats trailing dots as if they were a
+            // component of their own, that is, as the special
+            // relative paths.
+            // This seems to not be correctly handled by Qt's
+            // filesystem methods, resulting in inconsistencies when
+            // one such path is encountered.
+            // To avoid the issue, considering that an equivalent path
+            // can be formed by actually having the dots on their own
+            // as a component, we filter out all those paths that have
+            // trailing dots but are not only composed of dots.
+            Catch::Generators::filter(
+                [](auto& path){ return !(path.endsWith(".") && path.contains(QRegularExpression("[^.]"))) ; },
+                QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::portable_posix_directory_name()
+            ),
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::portable_posix_filename(),
+            QDOC_CATCH_GENERATORS_PRIVATE_NAMESPACE::windows_separator(),
+            PathGeneratorConfiguration{}
+                .set_multi_device_path_probability(multi_device_path_probability)
+                .set_absolute_path_probability(absolute_path_probability)
+                .set_directory_path_probability(directory_path_probability)
+        );
+    }
+
+    // TODO: Find a good way to test the following functions.
+    // native_path can probably be tied to the tests for the
+    // OS-specific functions, with TEMPLATE_TEST_CASE.
+    // The other ones may follow a similar pattern but require a bit
+    // more work so that they tie to a specific case instead of the
+    // general one.
+    // Nonetheless, this approach is both error prone and difficult to
+    // parse, because of the required if preprocessor directives,
+    // and should be avoided if possible.
+
+    /*!
+     * Returns a generator that generates QStrings that represents
+     * paths native to the underlying OS.
+     *
+     * On Windows, paths that refer to a drive always refer to the
+     * root drive.
+     *
+     * native* functions should always be chosen when using paths for
+     * testing interfacing with the filesystem itself.
+     *
+     * System outside Linux, macOS or Windows are not supported.
+     */
+    inline Catch::Generators::GeneratorWrapper<QString> native_path(double absolute_path_probability = 0.5, double directory_path_probability = 0.5) {
+#if defined(Q_OS_LINUX) || defined(Q_OS_MACOS)
+
+        return relaxed_portable_posix_path(absolute_path_probability, directory_path_probability);
+
+#elif defined(Q_OS_WINDOWS)
+
+        // REMARK: When generating native paths for testing we
+        // generally want to avoid relative paths that are
+        // drive-specific, as we want them to be tied to a specific
+        // working directory that may not be the current directory on
+        // the drive.
+        // Hence, we avoid generating paths that may have a drive component.
+        // For tests where those kind of paths are interesting, a
+        // specific Windows-only test should be made, using
+        // traditional_dos_path to generate drive-relative paths only.
+        return traditional_dos_path(absolute_path_probability, directory_path_probability, 0.0);
+
+#endif
+    }
+
+    /*!
+     * Returns a generator that generates QStrings that represents
+     * paths native to the underlying OS and that are always \e
+     * {Relative}.
+     *
+     * Avoids generating paths that refer to a directory that is not
+     * included in the path itself.
+     *
+     * System outside Linux, macOS or Windows are not supported.
+     */
+    inline Catch::Generators::GeneratorWrapper<QString> native_relative_path(double directory_path_probability = 0.5) {
+        // REMARK: When testing, we generally use some specific
+        // directory as a root for relative paths.
+        // We want the generated path to be relative to that
+        // directory because we need a clean state for the test to
+        // be reliable.
+        // When generating paths, it is possible, correctly, to
+        // have a path that refers to that directory or some
+        // parent of it, removing us from the clean state that we
+        // need.
+        // To avoid that, we filter out paths that end up referring to a directory that is not under our "root" directory.
+        //
+        // We can think of each generated component moving us
+        // further down or up, in case of "..", a directory
+        // hierarchy, or keeping us at the same place in case of
+        // ".".
+        // Any path that ends up under our original "root"
+        // directory will safely keep our clean state for testing.
+        //
+        // Each "." keeps us at the same level in the hierarchy.
+        // Each ".." moves us up one level in the hierarchy.
+        // Each component that is not "." or ".." moves us down
+        // one level into the hierarchy.
+        //
+        // Then, to avoid referring to the "root" directory or one
+        // of its parents, we need to balance out each "." and
+        // ".." with the components that precedes or follow their
+        // appearance.
+        //
+        // Since "." keeps us at the same level, it can appear how
+        // many times it wants as long as the path referes to the
+        // "root" directory or a directory or file under it and at
+        // least one other component referes to a directory or
+        // file that is under the "root" directory.
+        //
+        // Since ".." moves us one level up in the hierarchy, a
+        // sequence of n ".." components is safe when at least n +
+        // 1 non "." or ".." components appear before it.
+        //
+        // To avoid the above problem, we filter away paths that
+        // do not respect those rules.
+        return Catch::Generators::filter(
+            [](auto& path){
+                QStringList components{path.split(QRegularExpression{R"((\\|\/)+)"}, Qt::SkipEmptyParts)};
+                int depth{0};
+
+                for (auto& component : components) {
+                    if (component == "..")
+                        --depth;
+                    else if (component != ".")
+                        ++depth;
+
+                    if (depth < 0) return false;
+                }
+
+                return (depth > 0);
+            },
+            native_path(0.0, directory_path_probability)
+        );
+    }
+
+    /*!
+     * Returns a generator that generates QStrings that represents
+     * paths native to the underlying OS and that are always \e
+     * {Relative} and \e {To a File}.
+     *
+     * System outside Linux, macOS or Windows are not supported.
+     */
+    inline Catch::Generators::GeneratorWrapper<QString> native_relative_file_path() {
+        return native_relative_path(0.0);
+    }
+
+    /*!
+     * Returns a generator that generates QStrings that represents
+     * paths native to the underlying OS and that are always \e
+     * {Relative} and \e {To a Directory}.
+     *
+     * System outside Linux, macOS or Windows are not supported.
+     */
+    inline Catch::Generators::GeneratorWrapper<QString> native_relative_directory_path() {
+        return native_relative_path(1.0);
+    }
+
+} // end QDOC_CATCH_GENERATORS_ROOT_NAMESPACE