Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorLeitwolf2026-11-15 21:08:39 +0300
committerGitHub2026-11-15 21:08:39 +0300
commitb6f02aeb8ae8453a2e6a75d967e8cd7ad10e4020 (patch)
tree97b572e949b71640208615a4fdeb7b0b1bdc571a
parent7535282313ab3e4322d79e89f390e288bcf54999 (diff)
parent4de8706c37c67cf295421119b7a294716df02b5a (diff)
downloadtazelish-docs/code-of-conduct.tar.gz
Merge branch 'main' into docs/code-of-conductdocs/code-of-conduct
-rw-r--r--.github/workflows/ci.yml32
-rw-r--r--.gitignore1
-rw-r--r--Doxyfile27
-rw-r--r--Headers/Progmasoft/Tazelish/CommandLine.hpp24
-rw-r--r--Headers/Progmasoft/Tazelish/Help.hpp2
-rw-r--r--Headers/Progmasoft/Tazelish/Version.hpp27
-rw-r--r--Headers/Progmasoft/Tazelish/VersionFiles.hpp24
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"
diff --git a/.gitignore b/.gitignore
index 028ab83..a71dd6f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -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,