Merge pull request rust-osdev#673 from nicholasbishop/bishop-doc-unstable

xtask: Add `--unstable` option to `cargo xtask doc`

Author: phip1611

.github/workflows/rust.yml

@@ -93,9 +93,12 @@ jobs:
           rustup component add clippy
           cargo xtask clippy --warnings-as-errors
 
-      - name: Run cargo doc
+      - name: Run cargo doc (without unstable)
         run: cargo xtask doc --warnings-as-errors --document-private-items
 
+      - name: Run cargo doc (with unstable)
+        run: cargo xtask doc --warnings-as-errors --document-private-items --unstable
+
       - name: Verify generated code is up-to-date
         run: cargo xtask gen-code --check
 

uefi/src/mem.rs

@@ -29,6 +29,9 @@ use {core::alloc::Allocator, core::ptr::NonNull};
 /// `unstable`-feature, it uses the `allocator_api` instead. In that case, the function takes an
 /// additional parameter describing the specific [`Allocator`]. You can use [`alloc::alloc::Global`]
 /// as default.
+///
+/// [`Allocator`]: https://doc.rust-lang.org/alloc/alloc/trait.Allocator.html
+/// [`alloc::alloc::Global`]: https://doc.rust-lang.org/alloc/alloc/struct.Global.html
 pub(crate) fn make_boxed<
     'a,
     // The UEFI data structure.

uefi/src/proto/media/file/dir.rs

@@ -60,7 +60,8 @@ impl Directory {
         })
     }
 
-    /// Wrapper around [`Self::read_entry_boxed_in`] that uses the [`Global`] allocator.
+    /// Wrapper around [`Self::read_entry`] that returns an owned copy of the data. It has the same
+    /// implications and requirements. On failure, the payload of `Err` is `()´.
     #[cfg(feature = "alloc")]
     pub fn read_entry_boxed(&mut self) -> Result<Option<Box<FileInfo>>> {
         let read_entry_res = self.read_entry(&mut []);

uefi/src/proto/media/file/mod.rs

@@ -184,7 +184,7 @@ pub trait File: Sized {
         (self.imp().flush)(self.imp()).into()
     }
 
-    /// Wrapper around [`Self::get_boxed_info_in`] that uses the [`Global`] allocator.
+    /// Read the dynamically allocated info for a file.
     #[cfg(feature = "alloc")]
     fn get_boxed_info<Info: FileProtocolInfo + ?Sized + Debug>(&mut self) -> Result<Box<Info>> {
         let fetch_data_fn = |buf| self.get_info::<Info>(buf);

xtask/src/main.rs

@@ -94,8 +94,7 @@ fn doc(opt: &DocOpt) -> Result<()> {
             open: opt.open,
             document_private_items: opt.document_private_items,
         },
-        // for all possible features
-        features: Feature::more_code(true, true),
+        features: Feature::more_code(*opt.unstable, true),
         packages: Package::published(),
         release: false,
         target: None,

xtask/src/opt.rs

@@ -112,6 +112,9 @@ pub struct DocOpt {
     #[clap(long, action)]
     pub document_private_items: bool,
 
+    #[clap(flatten)]
+    pub unstable: UnstableOpt,
+
     #[clap(flatten)]
     pub warning: WarningOpt,
 }