xtask: Add --unstable option to cargo xtask doc

In preparation for testing on stable, make the `unstable` feature optional when
building docs.

This exposed a couple docstrings with links that broke without the `unstable`
feature. Fixed by changing `File::get_boxed_info` to have the same docstring as
`get_boxed_info_in`, and `Directory::read_entry_boxed` to have (almost) the same
docstring as `read_entry_boxed_in`.

The CI doc job now runs with and without `--unstable`.

Author: nicholasbishop

.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/proto/media/file/dir.rs

@@ -59,7 +59,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,
 }