Document the build scripts

- make items public.

DOCS/CHANGELOG.md

@@ -92,6 +92,7 @@ The format is based on [Keep a Changelog], and this project adheres to
 - new convenience fn: `manifest_dir` in `build::utils`.
 - hide `no_inline` items re-exports.
 - new file `DOCS/VENDORED_rustdoc.md`
+- document the build scripts.
 
 ### Removed
 - remove custom no_std `Error` definition.

build/environment.rs

@@ -1,9 +1,9 @@
 // devela build::utils
 //
-//! build script environment variables
+//! Build script environment variables.
 //
 
-pub(crate) fn main() -> Result<(), std::io::Error> {
+pub fn main() -> Result<(), std::io::Error> {
     let cargo_primary_package = option_env!("CARGO_PRIMARY_PACKAGE");
     if cargo_primary_package.is_some() {
         println!("cargo:rustc-cfg=cargo_primary_package");

build/features.rs

@@ -3,7 +3,7 @@
 //! Features debugging and compile flags enabling for reflexion.
 //
 
-pub(crate) fn main() -> Result<(), std::io::Error> {
+pub fn main() -> Result<(), std::io::Error> {
     #[cfg(feature = "__dbg")]
     crate::utils::println_heading("Features & Flags:");
 
@@ -16,7 +16,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> {
 //
 // https://doc.rust-lang.org/reference/conditional-compilation.html#set-configuration-options
 #[rustfmt::skip]
-mod reflection {
+pub mod reflection {
     #[cfg(feature = "__dbg")]
     use crate::utils::println;
     use std::env::var;
@@ -213,7 +213,7 @@ mod reflection {
     /// Set the flags for all the corresponding enabled features from the list.
     ///
     /// This is the list of the constants defined above.
-    pub(super) fn set_flags() {
+    pub fn set_flags() {
         for ff in [
             /* miscellaneous */
 

build/generate/mod.rs

@@ -4,9 +4,9 @@
 //
 
 #[cfg(feature = "_tuple")]
-mod tuple;
+pub mod tuple;
 
-pub(super) fn main() -> Result<(), std::io::Error> {
+pub fn main() -> Result<(), std::io::Error> {
     #[cfg(feature = "__dbg")]
     crate::utils::println_heading("Code generation:");
 

build/generate/tuple/mod.rs

@@ -25,7 +25,7 @@ use std::{
 };
 
 #[rustfmt::skip]
-pub(super) fn generate() -> Result<(), Error> {
+pub fn generate() -> Result<(), Error> {
     let build_out_dir = out_dir_path().join("build/");
     create_dir_all(&build_out_dir)?;
     let path = build_out_dir.join("tuple.rs");

build/mod.rs

@@ -1,21 +1,22 @@
 // devela build
 //
-//! The build script.
+//! The build scripts.
 //
 
-mod environment;
-mod features;
-mod generate;
-mod utils;
+#![expect(missing_docs, reason = "WIP: constants, main fns…")]
+
+pub mod environment;
+pub mod features;
+pub mod generate;
+pub mod utils;
 
 fn main() {
     if let Err(err) = try_main() {
         panic!("{}", err);
     }
 }
 
-// WAIT:1.81 [error_in_core](https://github.com/rust-lang/rust/pull/125951)
-fn try_main() -> Result<(), Box<dyn std::error::Error>> {
+fn try_main() -> Result<(), Box<dyn core::error::Error>> {
     #[cfg(feature = "__dbg")]
     utils::println_start_end(true);
 

build/utils.rs

@@ -8,32 +8,32 @@
 use std::{env, path::PathBuf};
 
 /// Retuns the path of `OUT_DIR`.
-pub(crate) fn out_dir_path() -> PathBuf {
+pub fn out_dir_path() -> PathBuf {
     PathBuf::from(env::var("OUT_DIR").expect("OUT_DIR not set"))
 }
 
 /// Retuns the path of `CARGO_MANIFEST_DIR`.
-pub(crate) fn manifest_dir_path() -> PathBuf {
+pub fn manifest_dir_path() -> PathBuf {
     PathBuf::from(env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set"))
 }
 
 /// Prints a message to *stdout* from the build script.
 #[cfg(feature = "__dbg")]
-pub(crate) fn println(msg: &str) {
+pub fn println(msg: &str) {
     println!("cargo:warning={}", msg);
 }
 
 /// Prints a heading message to *stdout*, underlined.
 #[cfg(feature = "__dbg")]
-pub(crate) fn println_heading(msg: &str) {
+pub fn println_heading(msg: &str) {
     println("");
     println(msg);
     println(&"-".repeat(msg.len()));
 }
 
 /// Prints the value of an environment variable.
 #[cfg(feature = "__dbg")]
-pub(crate) fn println_var(var: &str) {
+pub fn println_var(var: &str) {
     if let Ok(v) = env::var(var) {
         println(&format!["· {var}: {v}"]);
     } else {
@@ -44,7 +44,7 @@ pub(crate) fn println_var(var: &str) {
 
 /// Prints the build script `start` or end message to *stdout*.
 #[cfg(feature = "__dbg")]
-pub(crate) fn println_start_end(start: bool) {
+pub fn println_start_end(start: bool) {
     let msg = if start {
         "~ Start of build script ~"
     } else {

src/_doc/mod.rs

@@ -6,6 +6,10 @@
 #![cfg(any(doc, test))]
 #![cfg_attr(feature = "nightly_doc", doc(cfg(doc)))]
 
+#[cfg(feature = "std")]
+#[path = "../../build/mod.rs"]
+pub mod build;
+
 /// Documented examples.
 pub mod examples;