doc: add doc for moved files

src/yycc/env.hpp

@@ -4,15 +4,15 @@
 #include <expected>
 
 /**
- * @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.
+ * Rust standard library have so much robust environment-related operations,
- * Oppositly, C++ STL still lake in this even in today.
+ * such as environment variable operations, current program infos and etc.
- *
+ * Oppositly, C++ STL are still lack in this even in today.
- * The functions manipulating environment variable is different in different OS.
+ * So I create this namespace to glue all these things up, 
- * I create this namespace inspired from Rust standard library
+ * according to different operating systems, and make a uniform interface.
- * to glue all these things up and make a uniform interface.
  */
 namespace yycc::env {
 

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.
+ * Therefore, I suggest a good practice call "exception is error",
- * For this reason, registering any unhandled error callbacks which may resume the execution of program is prohibited to prevent unexpected continuation of execution.
+ * any C++ exception should be immediately treated as an error and cause the program to crash and exit.
- * For code we write ourselves that we can control, we should use the macros provided in this file instead of throwing exceptions.
+ * For this reason, registering any unhandled error callbacks which may resume the execution of program 
- * In this way, unexpected behavior in our code will cause the program to exit immediately, outputting error information and stack traces.
+ * 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 {
 

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 <vector>
 
+/**
+ * @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<typename T>
     using Vec = std::vector<T>;
 

src/yycc/primitive.hpp

@@ -3,6 +3,18 @@
 #include <cstddef>
 #include <string_view>
 
+/**
+ * @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;
 }