From ab8489c37760fb1bf015d3f531a83875571fcffa Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Tue, 7 Oct 2025 18:49:02 +0800 Subject: [PATCH] doc: add doc for moved files --- src/yycc/env.hpp | 14 +++++++------- src/yycc/panic.hpp | 11 +++++++---- src/yycc/prelude.hpp | 25 ++++++++++++++++++++++--- src/yycc/primitive.hpp | 15 ++++++++++++++- 4 files changed, 50 insertions(+), 15 deletions(-) diff --git a/src/yycc/env.hpp b/src/yycc/env.hpp index f9bbdcc..7118c6e 100644 --- a/src/yycc/env.hpp +++ b/src/yycc/env.hpp @@ -4,15 +4,15 @@ #include /** - * @brief The namespace providing environment variable operations. + * @brief The namespace providing runtime environment operations. + * @details * When I programming with Rust, I was astonished that - * Rust standard library have so much robust environment variable operations. - * Oppositly, C++ STL still lake in this even in today. - * - * The functions manipulating environment variable is different in different OS. - * I create this namespace inspired from Rust standard library - * to glue all these things up and make a uniform interface. + * Rust standard library have so much robust environment-related operations, + * such as environment variable operations, current program infos and etc. + * Oppositly, C++ STL are still lack in this even in today. + * So I create this namespace to glue all these things up, + * according to different operating systems, and make a uniform interface. */ namespace yycc::env { diff --git a/src/yycc/panic.hpp b/src/yycc/panic.hpp index dcbd479..9b3e6a2 100644 --- a/src/yycc/panic.hpp +++ b/src/yycc/panic.hpp @@ -15,11 +15,14 @@ * * Unfortunately, I cannot change the exception mechanism in the standard library. * The standard library will still throw exceptions where it does, and I cannot prevent that. - * Therefore, I suggest a good practice that any C++ exception should be immediately treated as an error and cause the program to crash and exit. - * For this reason, registering any unhandled error callbacks which may resume the execution of program is prohibited to prevent unexpected continuation of execution. - * For code we write ourselves that we can control, we should use the macros provided in this file instead of throwing exceptions. - * In this way, unexpected behavior in our code will cause the program to exit immediately, outputting error information and stack traces. + * Therefore, I suggest a good practice call "exception is error", + * any C++ exception should be immediately treated as an error and cause the program to crash and exit. + * For this reason, registering any unhandled error callbacks which may resume the execution of program + * is strictly prohibited to prevent any unexpected recovery from exceptions. + * For code your written, you should use the macros provided in this file instead of throwing exceptions. + * In this way, unexpected behavior in code will cause immediate exit, shown error information and stack traces. * Standard library exceptions will also cause the program to exit, but without stack information. + * However, if you are following "exception is error" rule, you still can throw exceptions instead. */ namespace yycc::panic { diff --git a/src/yycc/prelude.hpp b/src/yycc/prelude.hpp index cb79d67..f6a46de 100644 --- a/src/yycc/prelude.hpp +++ b/src/yycc/prelude.hpp @@ -1,4 +1,17 @@ #pragma once +/** + * @file + * @brief The Rust-like prelude header for C++. + * @details + * When I writting with Rust, I notice Rust add types for all files in default. + * This default imported types are called "prelude". + * This is very convenient for programming so I decide to introduce it in C++. + * + * I create this file, organize all types, which I think should be exposed for programmer, in to an independent namespace, + * and expose them into global namesoace. + * By simply include this file at the top of your C++ code, you can get Rust-like prelude effect in C++. + * These exposed types including primitive types, string types, basic Option and Result utilities, panic mechanisim and etc. +*/ // Rust prelude section #include "primitive.hpp" @@ -7,6 +20,13 @@ #include "panic.hpp" #include +/** + * @brief The namespace including all types presented in prelude. + * @details + * By including this file, all of these types are automaticalling exposed to global namespace. + * There is no need to refer this namespace anymore. + * This namespace is just a container for types which need to be exposed. + */ namespace yycc::prelude { // Include primitive types @@ -27,12 +47,11 @@ namespace yycc::prelude { using f32 = NS_YYCC_PRIMITIVE::f32; using f64 = NS_YYCC_PRIMITIVE::f64; - using str = NS_YYCC_PRIMITIVE::str; - #undef NS_YYCC_PRIMITIVE // Other types - using String = std::u8string; + //using str = std::u8string_view; + //using String = std::u8string; template using Vec = std::vector; diff --git a/src/yycc/primitive.hpp b/src/yycc/primitive.hpp index 970a17e..7ef1696 100644 --- a/src/yycc/primitive.hpp +++ b/src/yycc/primitive.hpp @@ -3,6 +3,18 @@ #include #include +/** + * @brief The namespace providing primitive types. + * @details + * When I writing with Rust, I notice that most pf primitive types has explicit and exact size, and their names are short and clear. + * Hoeever, in C++, most primitive types are variable based on system, due to the legacy of C era. + * All primitive types with explicit size are only can be fetched in a specific header file, + * and, their names are too long because they can not be registered as reserved keywords or names + * due to the name conflict with so much code written in past years. + * However, STL can't do this but I can do this. + * I invent this namespace providing primitive types, such as integers, floating-point numbers, and strings, + * in Rust style, their names areshort and clear. + */ namespace yycc::primitive { // `bool` is keyword so should not declare it anymore. @@ -23,5 +35,6 @@ namespace yycc::primitive { using f32 = float; using f64 = double; - using str = std::u8string_view; + // using String = std::u8string; + // using str = std::u8string_view; }