show docs for the build scripts (private)

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`
+- show docs for the build scripts (private).
 
 ### Removed
 - remove custom no_std `Error` definition.

build/environment.rs

@@ -1,6 +1,6 @@
 // devela build::utils
 //
-//! build script environment variables
+//! Build script environment variables.
 //
 
 pub(crate) fn main() -> Result<(), std::io::Error> {
@@ -11,7 +11,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> {
 
     #[cfg(feature = "__dbg")]
     {
-        use crate::utils::{println, println_heading, println_var};
+        use super::utils::{println, println_heading, println_var};
 
         // https://doc.rust-lang.org/cargo/reference/environment-variables.html
         println_heading("Environment variables:");
@@ -39,7 +39,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> {
         // println_var("CARGO_ENCODED_RUSTFLAGS");
 
         // for (key, value) in std::env::vars() {
-        //     crate::utils::println(&format![">> {key}: {value}"]);
+        //     super::utils::println(&format![">> {key}: {value}"]);
         // }
     }
 

build/features.rs

@@ -5,7 +5,7 @@
 
 pub(crate) fn main() -> Result<(), std::io::Error> {
     #[cfg(feature = "__dbg")]
-    crate::utils::println_heading("Features & Flags:");
+    super::utils::println_heading("Features & Flags:");
 
     reflection::set_flags();
 
@@ -18,7 +18,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> {
 #[rustfmt::skip]
 mod reflection {
     #[cfg(feature = "__dbg")]
-    use crate::utils::println;
+    use super::super::utils::println;
     use std::env::var;
 
     /// A type that associates a list of flags with a list of features.

build/generate/mod.rs

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

build/generate/tuple/mod.rs

@@ -9,7 +9,7 @@
 //! - enums definitions
 //! - iterators definitions and implementations
 
-use crate::utils::*;
+use super::super::utils::*;
 use std::{
     fs::{create_dir_all, read_to_string, File},
     io::{BufWriter, Error, Write},
@@ -25,7 +25,7 @@ use std::{
 };
 
 #[rustfmt::skip]
-pub(super) fn generate() -> Result<(), Error> {
+pub(crate) 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");
@@ -874,6 +874,6 @@ pub(super) fn generate() -> Result<(), Error> {
     }
 
     // #[cfg(doc)] // format the source if we're building the docs
-    // crate::rustfmt_file(path);
+    // super::super::rustfmt_file(path);
     Ok(())
 }

build/mod.rs

@@ -1,7 +1,11 @@
 // devela build
 //
-//! The build script.
+//! The build scripts.
 //
+// NOTE: use relative imports (super::*) instead of crate::*,
+// so that it also works when compiling private documentation.
+
+#![cfg_attr(feature = "nightly_doc", feature(doc_cfg, doc_notable_trait))]
 
 mod environment;
 mod features;
@@ -14,8 +18,7 @@ fn main() {
     }
 }
 
-// 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

@@ -19,12 +19,14 @@ pub(crate) fn manifest_dir_path() -> PathBuf {
 
 /// Prints a message to *stdout* from the build script.
 #[cfg(feature = "__dbg")]
+#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))]
 pub(crate) fn println(msg: &str) {
     println!("cargo:warning={}", msg);
 }
 
 /// Prints a heading message to *stdout*, underlined.
 #[cfg(feature = "__dbg")]
+#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))]
 pub(crate) fn println_heading(msg: &str) {
     println("");
     println(msg);
@@ -33,6 +35,7 @@ pub(crate) fn println_heading(msg: &str) {
 
 /// Prints the value of an environment variable.
 #[cfg(feature = "__dbg")]
+#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))]
 pub(crate) fn println_var(var: &str) {
     if let Ok(v) = env::var(var) {
         println(&format!["· {var}: {v}"]);
@@ -44,6 +47,7 @@ pub(crate) fn println_var(var: &str) {
 
 /// Prints the build script `start` or end message to *stdout*.
 #[cfg(feature = "__dbg")]
+#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))]
 pub(crate) fn println_start_end(start: bool) {
     let msg = if start {
         "~ Start of build script ~"

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"]
+mod build;
+
 /// Documented examples.
 pub mod examples;