tools: align internal rustdoc summaries

uefi-test-runner/src/bin/shell_launcher.rs

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! This application launches the UEFI shell app and runs the main
-//! uefi-test-running app inside that shell. This allows testing of protocols
+//! Launches the main test application inside the UEFI shell.
+//!
+//! This allows testing of protocols
 //! that require the shell.
 //!
 //! Launching the shell this way (rather than directly making it the boot
@@ -22,7 +23,9 @@ use uefi::proto::device_path::build::{self, DevicePathBuilder};
 use uefi::proto::device_path::{DevicePath, DeviceSubType, DeviceType, LoadedImageDevicePath};
 use uefi::proto::loaded_image::LoadedImage;
 
-/// Get the device path of the shell app. This is the same as the
+/// Returns the device path of the shell application.
+///
+/// This is the same as the
 /// currently-loaded image's device path, but with the file path part changed.
 fn get_shell_app_device_path(storage: &mut Vec<u8>) -> &DevicePath {
     let loaded_image_device_path =

uefi-test-runner/src/boot/misc.rs

@@ -137,7 +137,7 @@ fn test_watchdog() {
     boot::set_watchdog_timer(0, 0x10000, None).expect("Could not set watchdog timer");
 }
 
-/// Dummy protocol for tests
+/// Dummy protocol used by tests.
 #[unsafe_protocol("1a972918-3f69-4b5d-8cb4-cece2309c7f5")]
 struct TestProtocol {
     data: u32,

uefi-test-runner/src/main.rs

@@ -95,12 +95,13 @@ fn check_system() {
 
 #[derive(Clone, Copy, Debug)]
 enum HostRequest {
-    /// Tell the host to take a screenshot and compare against the
+    /// Tells the host to compare a screenshot with the
     /// golden image.
     Screenshot(&'static str),
 
-    /// Tell the host that tests are complete. The host will consider
-    /// the tests failed if this message is not received.
+    /// Tells the host that testing is complete.
+    ///
+    /// The host considers the tests failed if this message is not received.
     TestsComplete,
 }
 
@@ -156,9 +157,9 @@ fn reconnect_serial_to_console(serial_handle: Handle) {
         .expect("failed to reconnect serial to console");
 }
 
-/// Send the `request` string to the host via the `serial` device, then
-/// wait up to 10 seconds to receive a reply. Returns an error if the
-/// reply is not `"OK\n"`.
+/// Sends a request to the host through the serial device.
+///
+/// The function waits up to 10 seconds for an `"OK\n"` reply.
 fn send_request_to_host(request: HostRequest) {
     let serial_handle =
         uefi::boot::get_handle_for_protocol::<Serial>().expect("Failed to get serial handle");

uefi-test-runner/src/proto/media.rs

@@ -290,12 +290,12 @@ fn test_raw_disk_io(handle: Handle) {
     info!("Raw disk I/O succeeded");
 }
 
-/// Asynchronous disk I/O task context
+/// Context for an asynchronous disk I/O task.
 #[repr(C)]
 struct DiskIoTask {
-    /// Token for the transaction
+    /// Transaction token.
     token: DiskIo2Token,
-    /// Buffer holding the read data
+    /// Buffer that holds the read data.
     buffer: [u8; 512],
 }
 

xtask/src/cargo.rs

@@ -167,7 +167,7 @@ impl Feature {
 /// of types or some more specific combo.
 #[derive(Clone, Copy, Debug)]
 pub enum TargetTypes {
-    /// Use this to not specify any target types in the cargo command
+    /// Omits explicit target types from the Cargo command
     /// line; this will enable bins, libs, and tests if they are present.
     Default,
 
@@ -210,8 +210,9 @@ pub enum CargoAction {
     Test,
 }
 
-/// Get a modified PATH to remove entries added by rustup. This is
-/// necessary on Windows, see
+/// Returns `PATH` without entries added by rustup.
+///
+/// This is necessary on Windows; see
 /// <https://github.com/rust-lang/rustup/issues/3031>.
 fn sanitized_path(orig_path: OsString) -> OsString {
     // Modify the PATH to remove entries added by rustup. This is

xtask/src/check_raw.rs

@@ -136,8 +136,7 @@ impl Error {
     }
 }
 
-/// True if the visibility is public without restriction (i.e. just `pub`, not
-/// `pub(crate)` or similar).
+/// Returns whether visibility is unrestricted `pub`.
 fn is_pub(vis: &Visibility) -> bool {
     matches!(vis, Visibility::Public(_))
 }
@@ -158,8 +157,7 @@ enum Repr {
     Transparent,
 }
 
-/// A restricted view of `Attribute`, limited to just the attributes that are
-/// expected in `uefi-raw`.
+/// Restricted view of the attributes expected in `uefi-raw`.
 #[derive(Debug, Clone, Copy)]
 enum ParsedAttr {
     Allow(Allow),

xtask/src/device_path/field.rs

@@ -154,7 +154,7 @@ pub enum GetFunc {
     /// Autogenerate the getter.
     Auto,
 
-    /// Autogenerate the getter, but call a custom function to get the
+    /// Autogenerates the getter but uses a custom function for the
     /// return value.
     Custom,
 }
@@ -294,7 +294,9 @@ impl NodeField {
         ))
     }
 
-    /// Generate code to calculate the size of DST fields. Returns
+    /// Generates code that calculates the size of DST fields.
+    ///
+    /// Returns
     /// `None` for non-DST fields.
     pub fn gen_builder_dynamic_size(&self) -> Option<TokenStream> {
         if self.attr.custom_build_size_impl {
@@ -356,8 +358,9 @@ impl Default for FieldNodeAttr {
 }
 
 impl FieldNodeAttr {
-    /// Parse a field `node` attribute as described in the
-    /// readme. Returns `None` if the attribute does not exactly match
+    /// Parses a field `node` attribute as described in the readme.
+    ///
+    /// Returns `None` if the attribute does not exactly match
     /// the expected format.
     fn from_attr(attr: &Attribute) -> Option<Self> {
         if !attr.path().is_ident("node") {

xtask/src/device_path/node.rs

@@ -87,7 +87,9 @@ impl Node {
         self.fields.iter().filter(|field| field.is_slice()).count() > 1
     }
 
-    /// Calculate the static size of the packed structure. This should
+    /// Calculates the static size of the packed structure.
+    ///
+    /// This should
     /// give the same value as the `static_size` attribute.
     fn calculate_static_size(&self) -> usize {
         let header_size: usize = 4;
@@ -521,7 +523,9 @@ struct NodeAttr {
     sub_type: Option<String>,
 }
 
-/// Parse a `node` attribute. Returns `None` for any other attribute, or
+/// Parses a `node` attribute.
+///
+/// Returns `None` for any other attribute, or
 /// if the contents don't match the expected format.
 fn parse_node_attr(attr: &Attribute) -> Option<NodeAttr> {
     if !attr.path().is_ident("node") {
@@ -554,8 +558,7 @@ fn parse_node_attr(attr: &Attribute) -> Option<NodeAttr> {
     })
 }
 
-/// Returns `true` if the attribute is a valid `node` attribute, false
-/// otherwise.
+/// Returns whether the attribute is a valid `node` attribute.
 pub fn is_node_attr(attr: &Attribute) -> bool {
     parse_node_attr(attr).is_some()
 }

xtask/src/device_path/util.rs

@@ -6,7 +6,7 @@ use std::process::{Command, Stdio};
 use std::thread;
 use syn::Attribute;
 
-/// Returns true if the attribute is a `#[doc = "..."]` attribute,
+/// Returns whether the attribute is a `#[doc = "..."]` attribute,
 /// otherwise returns false.
 pub fn is_doc_attr(attr: &Attribute) -> bool {
     attr.path().is_ident("doc")

xtask/src/main.rs

@@ -193,7 +193,9 @@ fn run_vm_tests(opt: &QemuOpt) -> Result<()> {
     qemu::run_qemu(*opt.target, opt)
 }
 
-/// Run unit tests and doctests on the host. Most of uefi-rs is tested
+/// Runs unit tests and doctests on the host.
+///
+/// Most of uefi-rs is tested
 /// with VM tests, but a few things like macros and data types can be
 /// tested with regular tests.
 fn run_host_tests(test_opt: &TestOpt) -> Result<()> {

xtask/src/net.rs

@@ -5,8 +5,9 @@ use std::sync::{Arc, Mutex};
 use std::thread::{self, JoinHandle};
 use std::time::Duration;
 
-/// Run a simple echo service that listens on UDP port 21572 and
-/// reverses the incoming messages.
+/// Runs a simple echo service on UDP port 21572.
+///
+/// The service reverses incoming messages.
 pub struct EchoService {
     stop_requested: Arc<Mutex<bool>>,
 

xtask/src/opt.rs

@@ -88,7 +88,7 @@ pub struct BuildOpt {
     #[clap(flatten)]
     pub build_mode: BuildModeOpt,
 
-    /// Build multiple times to check that different feature
+    /// Builds multiple times to check that different feature
     /// combinations work.
     #[clap(long, action)]
     pub feature_permutations: bool,
@@ -130,8 +130,9 @@ pub struct DocOpt {
     #[clap(long, action)]
     pub open: bool,
 
-    /// Tells whether private items should be documented. This is convenient to check for
-    /// broken intra-doc links in private items.
+    /// Controls whether private items are documented.
+    ///
+    /// This is useful for finding broken intra-doc links in private items.
     #[clap(long, action)]
     pub document_private_items: bool,
 

xtask/src/pipe.rs

@@ -15,7 +15,9 @@ pub struct Pipe {
 }
 
 impl Pipe {
-    /// Prepare to set up a two-way communication pipe. This is called
+    /// Prepares a two-way communication pipe.
+    ///
+    /// This is called
     /// before launching QEMU. On Unix this uses `mkfifo` to create two
     /// pipes; on Windows QEMU itself will create the duplex pipe.
     pub fn new(dir: &Path, base_name: &'static str) -> Result<Self> {

xtask/src/qemu.rs

@@ -100,7 +100,7 @@ impl OvmfPaths {
         }
     }
 
-    /// Find path to OVMF files by the strategy documented for
+    /// Finds OVMF files using the strategy documented for
     /// [`Self::find_ovmf_file`].
     fn find(opt: &QemuOpt, arch: UefiArch) -> Result<Self> {
         let prebuilt_source = ovmf_prebuilt_source(arch);

xtask/src/util.rs

@@ -36,7 +36,7 @@ pub fn command_to_string(cmd: &Command) -> String {
     parts.into_iter().collect::<Vec<_>>().join(" ")
 }
 
-/// Print a `Command` and run it, then check that it completes
+/// Prints and runs a command, then checks that it succeeds.
 /// successfully.
 pub fn run_cmd(mut cmd: Command) -> Result<()> {
     println!("run_cmd: '{}'", command_to_string(&cmd));