diff options
| author | Leitwolf | 2026-11-15 21:08:39 +0300 |
|---|---|---|
| committer | GitHub | 2026-11-15 21:08:39 +0300 |
| commit | b6f02aeb8ae8453a2e6a75d967e8cd7ad10e4020 (patch) | |
| tree | 97b572e949b71640208615a4fdeb7b0b1bdc571a | |
| parent | 7535282313ab3e4322d79e89f390e288bcf54999 (diff) | |
| parent | 4de8706c37c67cf295421119b7a294716df02b5a (diff) | |
| download | tazelish-b6f02aeb8ae8453a2e6a75d967e8cd7ad10e4020.tar.gz | |
Merge branch 'main' into docs/code-of-conductdocs/code-of-conduct
| -rw-r--r-- | .github/workflows/ci.yml | 32 | ||||
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | Doxyfile | 27 | ||||
| -rw-r--r-- | Headers/Progmasoft/Tazelish/CommandLine.hpp | 24 | ||||
| -rw-r--r-- | Headers/Progmasoft/Tazelish/Help.hpp | 2 | ||||
| -rw-r--r-- | Headers/Progmasoft/Tazelish/Version.hpp | 27 | ||||
| -rw-r--r-- | Headers/Progmasoft/Tazelish/VersionFiles.hpp | 24 |
7 files changed, 134 insertions, 3 deletions
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 312777c..2046393 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -80,13 +80,39 @@ jobs: files: lcov.info fail_ci_if_error: true + doxygen: + name: Doxygen + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Install Doxygen + run: | + sudo apt-get update + sudo apt-get install --yes --no-install-recommends doxygen + + # Every warning fails, an undocumented declaration included. + - name: Build the reference of the headers + run: doxygen Doxyfile + + - name: Keep the reference + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: tazelish-doxygen + path: doxygen/html/ + if-no-files-found: error + retention-days: 7 + required: name: CI Required if: always() - needs: [test] + needs: [test, doxygen] runs-on: ubuntu-24.04 timeout-minutes: 5 steps: - env: - RESULT: ${{ needs.test.result }} - run: test "$RESULT" = success + RESULTS: ${{ needs.test.result }} ${{ needs.doxygen.result }} + run: test "$RESULTS" = "success success" @@ -4,3 +4,4 @@ /bazel-* /.cache/ /compile_commands.json +/doxygen/ diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..df05cc9 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,27 @@ +# SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> +# SPDX-License-Identifier: MIT +# +# The reference of the headers: doxygen writes doxygen/html. Every +# warning fails the build, an undocumented declaration included. + +PROJECT_NAME = Tazelish +PROJECT_BRIEF = "The installer of Tazel" +OUTPUT_DIRECTORY = doxygen +INPUT = README.md Headers +FILE_PATTERNS = *.hpp +RECURSIVE = YES +USE_MDFILE_AS_MAINPAGE = README.md +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +WARN_AS_ERROR = FAIL_ON_WARNINGS +QUIET = YES +GENERATE_HTML = YES +GENERATE_LATEX = NO +# The reference has no graphs, so nothing needs Graphviz. +HAVE_DOT = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = Headers +STRIP_FROM_INC_PATH = Headers diff --git a/Headers/Progmasoft/Tazelish/CommandLine.hpp b/Headers/Progmasoft/Tazelish/CommandLine.hpp index dc02c8e..f124368 100644 --- a/Headers/Progmasoft/Tazelish/CommandLine.hpp +++ b/Headers/Progmasoft/Tazelish/CommandLine.hpp @@ -21,13 +21,16 @@ namespace Progmasoft::Tazelish /// `tazelish install <version>`. struct Install { + /// The version to install. Version version; }; /// `tazelish use [--force] <version>`: writes `./tazelish.txt`. struct Use { + /// The version the project runs. Version version; + /// Whether an existing `tazelish.txt` is replaced. bool force = false; }; @@ -35,56 +38,77 @@ namespace Progmasoft::Tazelish /// user. struct Default { + /// The version the user runs outside a project. Version version; + /// Whether an existing `config.txt` is replaced. bool force = false; }; /// What `tazelish self` does to Tazelish itself. enum class SelfAction { + /// Update Tazelish. kUpdate, + /// Remove Tazelish and every version of Tazel it installed, and undo + /// the `PATH` entries it added. kRemove, + /// Do what kRemove does, and also delete what Tazelish kept for itself: + /// its `config.txt`, its download cache and its logs. kPurge, }; /// `tazelish self update|remove|purge`. struct Self { + /// What to do. SelfAction action = SelfAction::kUpdate; }; /// The commands `tazelish help <command>` explains. enum class Topic { + /// `tazelish help install`. kInstall, + /// `tazelish help use`. kUse, + /// `tazelish help default`. kDefault, + /// `tazelish help self`. kSelf, + /// `tazelish help help`. kHelp, }; /// `tazelish help [command]`; without a topic, the general help. struct Help { + /// The command to explain; nothing for the general help. std::optional<Topic> topic; }; + /// A command line that Tazelish accepts. using Command = std::variant<Install, Use, Default, Self, Help>; /// A command line that is wrong, and what is wrong with it. struct Rejection { + /// What is wrong, in a sentence for the user. std::string message; }; + /// The command a command line asks for, or why it asks for none. using ParseResult = std::variant<Command, Rejection>; /// The command [arguments] ask for; [arguments] leave out the name of the /// program. No arguments ask for the general help. + /// @param arguments The arguments after the name of the program. + /// @return The command, or the rejection of the command line. [[nodiscard]] ParseResult ParseCommandLine(const std::vector<std::string_view> &arguments); /// The name of a topic, as `tazelish help` takes it. + /// @param topic The topic. + /// @return Its name, such as `install`. [[nodiscard]] std::string_view TopicName(Topic topic); diff --git a/Headers/Progmasoft/Tazelish/Help.hpp b/Headers/Progmasoft/Tazelish/Help.hpp index a057adb..05cd362 100644 --- a/Headers/Progmasoft/Tazelish/Help.hpp +++ b/Headers/Progmasoft/Tazelish/Help.hpp @@ -15,6 +15,8 @@ namespace Progmasoft::Tazelish { /// The general help without a topic, or the help of one command. + /// @param topic The command to explain, or nothing. + /// @return The text to print, ending with a newline. [[nodiscard]] std::string_view HelpText(std::optional<Topic> topic); diff --git a/Headers/Progmasoft/Tazelish/Version.hpp b/Headers/Progmasoft/Tazelish/Version.hpp index ccd8e1a..2983486 100644 --- a/Headers/Progmasoft/Tazelish/Version.hpp +++ b/Headers/Progmasoft/Tazelish/Version.hpp @@ -18,34 +18,49 @@ namespace Progmasoft::Tazelish /// A release of Tazel: `MAJOR.SEMIMAJOR.MINOR.PATCH`. struct Release { + /// The first number. std::uint32_t majorNumber = 0; + /// The second number. std::uint32_t semimajorNumber = 0; + /// The third number. std::uint32_t minorNumber = 0; + /// The fourth number. std::uint32_t patchNumber = 0; }; /// The two kinds of build that are not releases. enum class Channel { + /// The `unstable` builds. kUnstable, + /// The `nightly` builds. kNightly, }; /// The newest build of a channel: `unstable` or `nightly`. struct Newest { + /// The channel. Channel channel = Channel::kUnstable; }; /// The build of a channel from one day: `YYYY-MM-DD-unstable`. struct Dated { + /// The year, such as 2026. std::uint16_t year = 0; + /// The month, from 1 to 12. std::uint8_t month = 0; + /// The day of the month, from 1. std::uint8_t day = 0; + /// The channel. Channel channel = Channel::kUnstable; }; + /// Whether two releases have the same four numbers. + /// @param left One release. + /// @param right The other release. + /// @return true when they are the same release. [[nodiscard]] inline bool operator==(const Release &left, const Release &right) { @@ -55,12 +70,20 @@ namespace Progmasoft::Tazelish && left.patchNumber == right.patchNumber; } + /// Whether two newest builds are of the same channel. + /// @param left One build. + /// @param right The other build. + /// @return true when the channels are the same. [[nodiscard]] inline bool operator==(const Newest &left, const Newest &right) { return left.channel == right.channel; } + /// Whether two dated builds are of the same day and channel. + /// @param left One build. + /// @param right The other build. + /// @return true when the date and the channel are the same. [[nodiscard]] inline bool operator==(const Dated &left, const Dated &right) { @@ -73,10 +96,14 @@ namespace Progmasoft::Tazelish /// The version [text] names, or nothing when it names none. Numbers have no /// leading zeros, and a date has to exist in the calendar. + /// @param text The text, such as `unstable` or a release number. + /// @return The version, or nothing. [[nodiscard]] std::optional<Version> ParseVersion(std::string_view text); /// The text of [version], the way ParseVersion reads it. + /// @param version The version. + /// @return Its text. [[nodiscard]] std::string FormatVersion(const Version &version); diff --git a/Headers/Progmasoft/Tazelish/VersionFiles.hpp b/Headers/Progmasoft/Tazelish/VersionFiles.hpp index cd0dc35..ed893f1 100644 --- a/Headers/Progmasoft/Tazelish/VersionFiles.hpp +++ b/Headers/Progmasoft/Tazelish/VersionFiles.hpp @@ -19,29 +19,39 @@ namespace Progmasoft::Tazelish { + /// The file of a project that names its version of Tazel. constexpr std::string_view kProjectFileName = "tazelish.txt"; + /// The folder in the home of the user where Tazelish keeps what it owns. constexpr std::string_view kStateDirectoryName = ".tazelish"; + /// The file in that folder that names the version of the user. constexpr std::string_view kConfigFileName = "config.txt"; /// A version file that could not be read or written, and why. struct FileError { + /// The file. std::filesystem::path file; + /// What went wrong, in a sentence for the user. std::string message; }; /// Which file named the version. enum class VersionSource { + /// The `tazelish.txt` of a project. kProject, + /// The `config.txt` of the user. kUser, }; /// The version to run and the file that named it. struct Selection { + /// The version to run. Version version; + /// The file that named it. std::filesystem::path file; + /// Which kind of file that is. VersionSource source = VersionSource::kProject; }; @@ -51,29 +61,43 @@ namespace Progmasoft::Tazelish /// The home folder of the user: `%USERPROFILE%` on Windows, `$HOME` /// elsewhere; nothing when the variable is unset or empty. + /// @return The folder, or nothing. [[nodiscard]] std::optional<std::filesystem::path> HomeDirectory(); /// `<home>/.tazelish`, where Tazelish keeps what it owns. + /// @param home The home folder of the user. + /// @return The folder. [[nodiscard]] std::filesystem::path StateDirectory(const std::filesystem::path &home); /// `<home>/.tazelish/config.txt`. + /// @param home The home folder of the user. + /// @return The file. [[nodiscard]] std::filesystem::path ConfigFile(const std::filesystem::path &home); /// The version [file] names; NoSelection when it does not exist. + /// @param file The version file. + /// @return The version, NoSelection, or why the file could not be read. [[nodiscard]] std::variant<NoSelection, Version, FileError> ReadVersionFile(const std::filesystem::path &file); /// The version to run in [directory]: the nearest `tazelish.txt` in it or a /// folder above it, else the `config.txt` of [home]. + /// @param directory The folder the command runs in. + /// @param home The home folder of the user, or nothing. + /// @return The selection, NoSelection, or why a file could not be read. [[nodiscard]] std::variant<NoSelection, Selection, FileError> SelectVersion(const std::filesystem::path &directory, const std::optional<std::filesystem::path> &home); /// Writes [version] to [file], creating its folder. An existing file is an /// error unless [force] is set. + /// @param file The version file. + /// @param version The version to write. + /// @param force Whether an existing file is replaced. + /// @return Nothing on success, or why the file could not be written. [[nodiscard]] std::optional<FileError> WriteVersionFile(const std::filesystem::path &file, const Version &version, |