✍ Improve the documentation a tiny bit

- 🛠 Fix the install target for CMake for the library

.gitignore

@@ -1,6 +1,7 @@
 build/
+install/
 .vscode/
 .mypy_cache/
 /main.cpp
-.vs
-CMakeSettings.json
+.vs
+CMakeSettings.json

.readthedocs.yml

@@ -1,3 +1,32 @@
+# =============================================================================
+#
+# ztd.text
+# Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+# Contact: opensource@soasis.org
+#
+# Commercial License Usage
+# Licensees holding valid commercial ztd.cuneicode licenses may use this file in
+# accordance with the commercial license agreement provided with the
+# Software or, alternatively, in accordance with the terms contained in
+# a written agreement between you and Shepherd's Oasis, LLC.
+# For licensing terms and conditions see your agreement. For
+# further information contact opensource@soasis.org.
+#
+# Apache License Version 2 Usage
+# Alternatively, this file may be used under the terms of Apache License
+# Version 2.0 (the "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+#      http:#www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# =============================================================================
+
 # .readthedocs.yml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

CMakeLists.txt

@@ -97,14 +97,15 @@ else()
 	set(ztd_text_has_cuneicode OFF)
 endif()
 
-file(GLOB ztd.text.includes CONFIGURE_DEPENDS include/*.hpp)
+file(GLOB_RECURSE ztd.text.includes CONFIGURE_DEPENDS include/*.hpp)
 
 # Check environment/prepare generator expressions
 check_cxx_compiler_flag(/permissive- ZTD_TEXT_MSVC_DISABLE_PERMISSIVE)
 
 check_cxx_compiler_flag(-Wpedantic ZTD_TEXT_DIAGNOSTIC_PEDANTIC)
 check_cxx_compiler_flag(-Werror ZTD_TEXT_DIAGNOSTIC_ERRORS)
 check_cxx_compiler_flag(-Wall ZTD_TEXT_DIAGNOSTIC_DEFAULTS)
+check_cxx_compiler_flag(-W4 ZTD_TEXT_MSVC_DIAGNOSTIC_DEFAULTS)
 
 string(CONCAT ztd-text-is-top-level $<STREQUAL:${PROJECT_NAME},${CMAKE_PROJECT_NAME}>)
 string(CONCAT --disable-permissive $<
@@ -124,11 +125,18 @@ string(CONCAT --warn-pedantic $<$<BOOL:${ZTD_TEXT_DIAGNOSTIC_PEDANTIC}>:-Wpedant
 string(CONCAT --warn-default $<
 	$<AND:
 		$<BOOL:${ZTD_TEXT_DIAGNOSTIC_DEFAULTS}>,
-		$<NOT:$<BOOL:MSVC>>,
+		$<NOT:$<BOOL:MSVC>>
 	>:-Wall
 >)
+string(CONCAT --warn-default $<
+	$<AND:
+		$<BOOL:${ZTD_TEXT_MSVC_DIAGNOSTIC_DEFAULTS}>,
+		$<BOOL:MSVC>
+	>:-W4
+>)
 string(CONCAT --deny-errors $<$<BOOL:${ZTD_TEXT_DIAGNOSTIC_ERRORS}>:-Werror>)
 
+
 add_library(ztd.text INTERFACE)
 add_library(ztd::text ALIAS ztd.text)
 target_include_directories(ztd.text
@@ -139,10 +147,8 @@ target_compile_features(ztd.text INTERFACE $<${ztd-text-is-top-level}:cxx_std_20
 target_compile_options(ztd.text INTERFACE ${--disable-permissive})
 target_sources(ztd.text INTERFACE ${ztd.text.includes})
 target_link_libraries(ztd.text INTERFACE ${ztd-use-cuneicode})
-
-set_target_properties(ztd.text
-	PROPERTIES
-	EXPORT_NAME ztd::text
+install(DIRECTORY include/
+	DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
 # # Config / Version packaging

documentation/CMakeLists.txt

@@ -28,14 +28,18 @@
 #
 # ============================================================================>
 
+# Dependencies
 find_package(Doxygen REQUIRED)
 find_package(Python3 REQUIRED)
 find_package(Sphinx QUIET)
 
+# For the install target and related directories
+include(GNUInstallDirs)
+
 # Find all the public headers
 file(GLOB_RECURSE ztd_text_public_headers
-  LIST_DIRECTORIES NO
-  CONFIGURE_DEPENDS ${PROJECT_SOURCE_DIR}/include/**.*)
+	LIST_DIRECTORIES NO
+	CONFIGURE_DEPENDS ${PROJECT_SOURCE_DIR}/include/**.*)
 # make a list copy for use with dependency tracking later down below
 set(ztd_text_doxygen_public_headers ${ztd_text_public_headers})
 # Remove every single public header
@@ -59,8 +63,8 @@ set(ZTD_TEXT_SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
 
 # Get all Sphinx source files
 file(GLOB_RECURSE ztd_text_sphinx_sources
-  LIST_DIRECTORIES NO
-  CONFIGURE_DEPENDS ${ZTD_TEXT_SPHINX_SOURCE_DIR}/**.*)
+	LIST_DIRECTORIES NO
+	CONFIGURE_DEPENDS ${ZTD_TEXT_SPHINX_SOURCE_DIR}/**.*)
 
 #Replace variables inside @@ with the current values
 configure_file(${ZTD_TEXT_DOXYFILE_IN} ${ZTD_TEXT_DOXYFILE_OUT} @ONLY)
@@ -72,10 +76,10 @@ file(MAKE_DIRECTORY ${ZTD_TEXT_DOXYGEN_HTML_OUTPUT_DIR})
 file(MAKE_DIRECTORY ${ZTD_TEXT_SPHINX_BUILD_DIR})
 
 set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES
-  ${ZTD_TEXT_DOXYGEN_XML_OUTPUT_DIR}
-  ${ZTD_TEXT_DOXYGEN_HTML_OUTPUT_DIR}
-  ${ZTD_TEXT_DOXYGEN_OUTPUT_DIR}
-  ${ZTD_TEXT_SPHINX_BUILD_DIR})
+	${ZTD_TEXT_DOXYGEN_XML_OUTPUT_DIR}
+	${ZTD_TEXT_DOXYGEN_HTML_OUTPUT_DIR}
+	${ZTD_TEXT_DOXYGEN_OUTPUT_DIR}
+	${ZTD_TEXT_SPHINX_BUILD_DIR})
 
 add_custom_command(OUTPUT ${ZTD_TEXT_DOXYGEN_INDEX_FILE}
 	COMMAND ${DOXYGEN_EXECUTABLE} ${ZTD_TEXT_DOXYFILE_OUT}
@@ -87,22 +91,19 @@ add_custom_target(ztd.text.documentation.doxygen ALL DEPENDS ${ZTD_TEXT_DOXYGEN_
 
 if (NOT ZTD_TEXT_DOCUMENTATION_NO_SPHINX)
 	add_custom_target(ztd.text.documentation.sphinx ALL
-    COMMAND Sphinx::Build
-      -b html
-      -Dbreathe_projects.ztd.text=${ZTD_TEXT_DOXYGEN_XML_OUTPUT_DIR}
-      ${ZTD_TEXT_SPHINX_SOURCE_DIR}
-      ${ZTD_TEXT_SPHINX_BUILD_DIR}
-    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-    DEPENDS ${ZTD_TEXT_DOXYGEN_INDEX_FILE} ${ztd_text_sphinx_sources}
-    COMMENT "[ztd.text/documentation] Generating Sphinx documentation..."
-    COMMAND_EXPAND_LISTS
-    VERBATIM)
+		COMMAND Sphinx::Build
+			-b html
+			-Dbreathe_projects.ztd.text=${ZTD_TEXT_DOXYGEN_XML_OUTPUT_DIR}
+			${ZTD_TEXT_SPHINX_SOURCE_DIR}
+			${ZTD_TEXT_SPHINX_BUILD_DIR}
+		WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+		DEPENDS ${ZTD_TEXT_DOXYGEN_INDEX_FILE} ${ztd_text_sphinx_sources}
+		COMMENT "[ztd.text/documentation] Generating Sphinx documentation..."
+		COMMAND_EXPAND_LISTS
+		VERBATIM)
 
 	add_dependencies(ztd.text.documentation.sphinx ztd.text.documentation.doxygen)
-endif()
 
-# For the install target
-include(GNUInstallDirs)
-install(DIRECTORY ${ZTD_TEXT_SPHINX_BUILD_DIR}
-	DESTINATION ${CMAKE_INSTALL_DOCDIR}
-)
+	install(DIRECTORY ${ZTD_TEXT_SPHINX_BUILD_DIR}
+		DESTINATION ${CMAKE_INSTALL_DOCDIR})
+endif()

documentation/source/api/encodings/encoding_scheme.rst

@@ -38,22 +38,30 @@ The ``encoding_scheme`` template turns any encoding into a byte-based encoding c
 Aliases
 -------
 
+.. doxygentypedef:: ztd::text::basic_utf16_le
+
 .. doxygentypedef:: ztd::text::utf16_le
 
-.. doxygentypedef:: ztd::text::basic_utf16_le
+.. doxygentypedef:: ztd::text::basic_utf16_be
 
 .. doxygentypedef:: ztd::text::utf16_be
 
-.. doxygentypedef:: ztd::text::basic_utf16_be
+.. doxygentypedef:: ztd::text::basic_utf16_ne
 
-.. doxygentypedef:: ztd::text::utf32_le
+.. doxygentypedef:: ztd::text::utf16_ne
 
 .. doxygentypedef:: ztd::text::basic_utf32_le
 
-.. doxygentypedef:: ztd::text::utf32_be
+.. doxygentypedef:: ztd::text::utf32_le
 
 .. doxygentypedef:: ztd::text::basic_utf32_be
 
+.. doxygentypedef:: ztd::text::utf32_be
+
+.. doxygentypedef:: ztd::text::basic_utf32_ne
+
+.. doxygentypedef:: ztd::text::utf32_ne
+
 
 
 Base Template

include/ztd/text/any_encoding.hpp

@@ -962,11 +962,11 @@ namespace ztd { namespace text {
 
 	//////
 	/// @brief An encoding type that wraps up other encodings to specifically traffic in the given @p _Byte type
-	/// provided, which is typically set to @c "std::byte".
+	/// provided, which is typically set to @c std::byte .
 	///
-	/// @tparam _Byte The byte type to use. Typically, this is either @c "unsigned char" or @c "std::byte".
+	/// @tparam _Byte The byte type to use. Typically, this is either <tt>unsigned char</tt> or @c std::byte .
 	///
-	/// @remarks This type traffics solely in @c "std::span"s, which for most people is fine. Others may want to
+	/// @remarks This type traffics solely in @c std::span s, which for most people is fine. Others may want to
 	/// interface with different iterator types (e.g., from a custom Rope implementation or other). For those, one must
 	/// first create ranges that can operate with those iterators, then use them themselves. (It's not an ideal process
 	/// at the moment, and we are looking to make this experience better.) It is recommended to use the provided

include/ztd/text/char8_t.hpp

@@ -48,7 +48,7 @@ namespace ztd { namespace text {
 	/// @brief An alias to a unsigned representation of an 8-bit (or greater) code unit type.
 	///
 	/// @remarks This will be a type alias for the type given in @c ZTD_TEXT_CHAR8_T is defined by the user. Otherwise,
-	/// it will be a type alias for @c char8_t if present. If neither are available, it will alias @c unsigned @c char
+	/// it will be a type alias for @c char8_t if present. If neither are available, it will alias @c uchar
 	/// for the type.
 	//////
 	using uchar8_t = ZTD_TEXT_CHAR8_T_I_;

include/ztd/text/code_unit.hpp

@@ -15,7 +15,7 @@
 // Apache License Version 2 Usage
 // Alternatively, this file may be used under the terms of Apache License
 // Version 2.0 (the "License") for non-commercial use; you may not use this
-// file except in compliance with the License. You may obtain a copy of the 
+// file except in compliance with the License. You may obtain a copy of the
 // License at
 //
 //		http://www.apache.org/licenses/LICENSE-2.0
@@ -44,11 +44,10 @@ namespace ztd { namespace text {
 	//////
 	/// @addtogroup ztd_text_properties Property and Trait Helpers
 	///
-	/// @brief Type-trait like properties and helpers, with @c _t (@c "typename ... ::type") and @c _v (@c "inline
-	/// constexpr bool ... ::value").
+	/// @brief Type-trait like properties and helpers, with @c _t ( @c \::type ) and @c _v ( @c \::value ).
 	///
 	/// @remarks These should be the go-to way to reference necessary type and constant static data out of encoding
-	/// objects when not interfacing with the well-defined, guaranteed members. For example, accessing the @c
+	/// objects when not interfacing with the well-defined, guaranteed members. For example, directly accessing the @c
 	/// obj::code_unit type is not viable for many encoding types and it is best to go through here.
 	/// @{
 	/////

include/ztd/text/encoding_scheme.hpp

@@ -406,21 +406,21 @@ namespace ztd { namespace text {
 			using _UInputRange   = __txt_detail::__remove_cvref_t<_InputRange>;
 			using _UOutputRange  = __txt_detail::__remove_cvref_t<_OutputRange>;
 			using _UErrorHandler = __txt_detail::__remove_cvref_t<_ErrorHandler>;
-			using _Result = __txt_detail::__reconstruct_decode_result_t<_UInputRange, _UOutputRange, decode_state>;
-			using _InByteIt
-				= __txt_detail::__word_iterator<_BaseCodeUnit, __txt_detail::__range_iterator_t<_UInputRange>, _Endian>;
+			using _Result   = __txt_detail::__reconstruct_decode_result_t<_UInputRange, _UOutputRange, decode_state>;
+			using _InByteIt = __txt_detail::__word_iterator<_BaseCodeUnit,
+				__txt_detail::__range_iterator_t<_UInputRange>, _Endian>;
 			using _InByteSen = __txt_detail::__word_sentinel<__txt_detail::__range_sentinel_t<_UInputRange>>;
 
 			auto __init   = __txt_detail::__adl::__adl_cbegin(__input);
 			auto __inlast = __txt_detail::__adl::__adl_cend(__input);
 			subrange<_InByteIt, _InByteSen> __inbytes(
 				_InByteIt(::std::move(__init)), _InByteSen(::std::move(__inlast)));
-			__txt_detail::__scheme_decode_handler<_Byte, _UInputRange, _UOutputRange, _UErrorHandler> __scheme_handler(
-				__error_handler);
+			__txt_detail::__scheme_decode_handler<_Byte, _UInputRange, _UOutputRange, _UErrorHandler>
+				__scheme_handler(__error_handler);
 			auto __result
 				= this->base().decode_one(__inbytes, ::std::forward<_OutputRange>(__output), __scheme_handler, __s);
-			return _Result(__txt_detail::__reconstruct(::std::in_place_type<_UInputRange>, __result.input.begin().base(),
-				               __result.input.end().base()),
+			return _Result(__txt_detail::__reconstruct(::std::in_place_type<_UInputRange>,
+				               __result.input.begin().base(), __result.input.end().base()),
 				__txt_detail::__reconstruct(::std::in_place_type<_UOutputRange>, ::std::move(__result.output)), __s,
 				__result.error_code, __result.handled_errors);
 		}
@@ -448,9 +448,9 @@ namespace ztd { namespace text {
 			encode_state& __s) const {
 			using _UInputRange  = __txt_detail::__remove_cvref_t<_InputRange>;
 			using _UOutputRange = __txt_detail::__remove_cvref_t<_OutputRange>;
-			using _Result       = __txt_detail::__reconstruct_encode_result_t<_UInputRange, _UOutputRange, encode_state>;
-			using _OutByteIt
-				= __txt_detail::__word_iterator<_BaseCodeUnit, __txt_detail::__range_iterator_t<_UOutputRange>, _Endian>;
+			using _Result = __txt_detail::__reconstruct_encode_result_t<_UInputRange, _UOutputRange, encode_state>;
+			using _OutByteIt  = __txt_detail::__word_iterator<_BaseCodeUnit,
+                    __txt_detail::__range_iterator_t<_UOutputRange>, _Endian>;
 			using _OutByteSen = __txt_detail::__word_sentinel<__txt_detail::__range_sentinel_t<_UOutputRange>>;
 
 			auto __outit   = __txt_detail::__adl::__adl_begin(__output);
@@ -469,23 +469,23 @@ namespace ztd { namespace text {
 	//////
 	/// @brief A UTF-16 encoding, in Little Endian format, with inputs as a sequence of bytes.
 	///
-	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or @c unsigned char.
+	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or @c uchar.
 	//////
 	template <typename _Byte>
 	using basic_utf16_le = encoding_scheme<utf16, endian::little, _Byte>;
 
 	//////
 	/// @brief A UTF-16 encoding, in Big Endian format, with inputs as a sequence of bytes.
 	///
-	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or @c "unsigned char" .
+	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or <tt>unsigned char</tt>.
 	//////
 	template <typename _Byte>
 	using basic_utf16_be = encoding_scheme<utf16, endian::big, _Byte>;
 
 	//////
 	/// @brief A UTF-16 encoding, in Native Endian format, with inputs as a sequence of bytes.
 	///
-	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or @c "unsigned char" .
+	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or <tt>unsigned char</tt>.
 	//////
 	template <typename _Byte>
 	using basic_utf16_ne = encoding_scheme<utf16, endian::native, _Byte>;
@@ -511,23 +511,23 @@ namespace ztd { namespace text {
 	//////
 	/// @brief A UTF-32 encoding, in Little Endian format, with inputs as a sequence of bytes.
 	///
-	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or @c "unsigned char" .
+	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or <tt>unsigned char</tt> .
 	//////
 	template <typename _Byte>
 	using basic_utf32_le = encoding_scheme<utf32, endian::little, _Byte>;
 
 	//////
 	/// @brief A UTF-32 encoding, in Big Endian format, with inputs as a sequence of bytes.
 	///
-	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or @c "unsigned char" .
+	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or <tt>unsigned char</tt> .
 	//////
 	template <typename _Byte>
 	using basic_utf32_be = encoding_scheme<utf32, endian::big, _Byte>;
 
 	//////
 	/// @brief A UTF-32 encoding, in Native Endian format, with inputs as a sequence of bytes.
 	///
-	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or @c "unsigned char" .
+	/// @tparam _Byte The byte type to use. Typically, this is @c std::byte or <tt>unsigned char</tt> .
 	//////
 	template <typename _Byte>
 	using basic_utf32_ne = encoding_scheme<utf32, endian::native, _Byte>;

include/ztd/text/is_code_points_replaceable.hpp

@@ -61,15 +61,15 @@ namespace ztd { namespace text {
 	/// @tparam _Type The type to check for the proper function call.
 	///
 	/// @remarks The @c value boolean is true if the given @p _Type has a function named @c
-	/// maybe_replacement_code_points() on it that can be called from a const-qualified @c "const _Type" which returns
-	/// a @c std::optional containing a contiguous view of code points.
+	/// maybe_replacement_code_points() on it that can be called from a @c const -qualified @p _Type object which
+	/// returns a @c std::optional containing a contiguous view of code points.
 	//////
 	template <typename _Type>
 	class is_code_points_maybe_replaceable
 	: public __txt_detail::__is_detected<__txt_detail::__detect_is_code_points_maybe_replaceable, _Type> { };
 
 	//////
-	/// @brief A @c value alias for ztd::text::is_code_points_maybe_replaceable
+	/// @brief A @c \::value alias for ztd::text::is_code_points_maybe_replaceable
 	///
 	//////
 	template <typename _Type>
@@ -81,15 +81,15 @@ namespace ztd { namespace text {
 	/// @tparam _Type The type to check for the proper function call.
 	///
 	/// @remarks The @c value boolean is true if the given @p _Type has a function named @c
-	/// replacement_code_points() on it that can be called from a const-qualified @c "const _Type" which returns a
+	/// replacement_code_points() on it that can be called from a @c const -qualified @c _Type object which returns a
 	/// contiguous view of code points.
 	//////
 	template <typename _Type>
 	class is_code_points_replaceable
 	: public __txt_detail::__is_detected<__txt_detail::__detect_is_code_points_replaceable, _Type> { };
 
 	//////
-	/// @brief A @c value alias for ztd::text::is_code_points_replaceable
+	/// @brief A @c \::value alias for ztd::text::is_code_points_replaceable
 	///
 	//////
 	template <typename _Type>