Merge pull request #5661 from arihant2math/doc

youknowone · web-flow · commit e0a35e4322dc · 2025-04-05T14:49:41.000+09:00
Fix doc warnings
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -325,6 +325,8 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
       - name: install ruff
         run: python -m pip install ruff==0.0.291 # astral-sh/ruff#7778
+      - name: Ensure docs generate no warnings
+        run: cargo doc
       - name: run python lint
         run: ruff extra_tests wasm examples  --exclude='./.*',./Lib,./vm/Lib,./benches/ --select=E9,F63,F7,F82 --show-source
       - name: install prettier
diff --git a/common/src/linked_list.rs b/common/src/linked_list.rs
@@ -1,4 +1,4 @@
-//! This module is modified from tokio::util::linked_list: https://github.com/tokio-rs/tokio/blob/master/tokio/src/util/linked_list.rs
+//! This module is modified from tokio::util::linked_list: <https://github.com/tokio-rs/tokio/blob/master/tokio/src/util/linked_list.rs>
 //! Tokio is licensed under the MIT license:
 //!
 //! Copyright (c) 2021 Tokio Contributors
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,9 +1,9 @@
 //! This is the `rustpython` binary. If you're looking to embed RustPython into your application,
-//! you're likely looking for the [`rustpython-vm`](https://docs.rs/rustpython-vm) crate.
+//! you're likely looking for the [`rustpython_vm`] crate.
 //!
 //! You can install `rustpython` with `cargo install rustpython`, or if you'd like to inject your
 //! own native modules you can make a binary crate that depends on the `rustpython` crate (and
-//! probably `rustpython-vm`, too), and make a `main.rs` that looks like:
+//! probably [`rustpython_vm`], too), and make a `main.rs` that looks like:
 //!
 //! ```no_run
 //! use rustpython_vm::{pymodule, py_freeze};
diff --git a/src/settings.rs b/src/settings.rs
@@ -13,7 +13,11 @@ pub enum RunMode {
 }
 
 pub enum InstallPipMode {
+    /// Install pip using the ensurepip pip module. This has a higher chance of
+    /// success, but may not install the latest version of pip.
     Ensurepip,
+    /// Install pip using the get-pip.py script, which retrieves the latest pip version.
+    /// This can be broken due to incompatibilities with cpython.
     GetPip,
 }
 
diff --git a/src/shell.rs b/src/shell.rs
@@ -71,6 +71,7 @@ fn shell_exec(
     }
 }
 
+/// Enter a repl loop
 pub fn run_shell(vm: &VirtualMachine, scope: Scope) -> PyResult<()> {
     let mut repl = Readline::new(helper::ShellHelper::new(vm, scope.globals.clone()));
     let mut full_input = String::new();
diff --git a/stdlib/src/pystruct.rs b/stdlib/src/pystruct.rs
@@ -1,9 +1,9 @@
 //! Python struct module.
 //!
-//! Docs: https://docs.python.org/3/library/struct.html
+//! Docs: <https://docs.python.org/3/library/struct.html>
 //!
 //! Use this rust module to do byte packing:
-//! https://docs.rs/byteorder/1.2.6/byteorder/
+//! <https://docs.rs/byteorder/1.2.6/byteorder/>
 
 pub(crate) use _struct::make_module;
 
diff --git a/vm/src/builtins/mod.rs b/vm/src/builtins/mod.rs
@@ -1,6 +1,6 @@
 //! This package contains the python basic/builtin types
-//! 7 common PyRef type aliases are exposed - PyBytesRef, PyDictRef, PyIntRef, PyListRef, PyStrRef, PyTypeRef, PyTupleRef
-//! Do not add more PyRef type aliases. They will be rare enough to use directly PyRef<T>.
+//! 7 common PyRef type aliases are exposed - [`PyBytesRef`], [`PyDictRef`], [`PyIntRef`], [`PyListRef`], [`PyStrRef`], [`PyTypeRef`], [`PyTupleRef`]
+//! Do not add more PyRef type aliases. They will be rare enough to use directly `PyRef<T>`.
 
 pub(crate) mod asyncgenerator;
 pub use asyncgenerator::PyAsyncGen;
diff --git a/vm/src/dict_inner.rs b/vm/src/dict_inner.rs
@@ -1,7 +1,7 @@
 //! Ordered dictionary implementation.
-//! Inspired by: https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html
-//! And: https://www.youtube.com/watch?v=p33CVV29OG8
-//! And: http://code.activestate.com/recipes/578375/
+//! Inspired by: <https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html>
+//! And: <https://www.youtube.com/watch?v=p33CVV29OG8>
+//! And: <http://code.activestate.com/recipes/578375/>
 
 use crate::{
     AsObject, Py, PyExact, PyObject, PyObjectRef, PyRefExact, PyResult, VirtualMachine,
diff --git a/vm/src/function/builtin.rs b/vm/src/function/builtin.rs
@@ -65,7 +65,7 @@ const fn zst_ref_out_of_thin_air<T: 'static>(x: T) -> &'static T {
     }
 }
 
-/// Get the [`STATIC_FUNC`](IntoPyNativeFn::STATIC_FUNC) of the passed function. The same
+/// Get the STATIC_FUNC of the passed function. The same
 /// requirements of zero-sizedness apply, see that documentation for details.
 ///
 /// Equivalent to [`IntoPyNativeFn::into_func()`], but usable in a const context. This is only
diff --git a/vm/src/import.rs b/vm/src/import.rs
@@ -1,6 +1,5 @@
-/*
- * Import mechanics
- */
+//! Import mechanics
+
 use crate::{
     AsObject, PyObjectRef, PyPayload, PyRef, PyResult, TryFromObject,
     builtins::{PyBaseExceptionRef, PyCode, list, traceback::PyTraceback},
diff --git a/vm/src/lib.rs b/vm/src/lib.rs
@@ -1,9 +1,10 @@
-//! This crate contains most python logic.
+//! This crate contains most of the python logic.
 //!
-//! - Compilation
-//! - Bytecode
+//! - Interpreter
 //! - Import mechanics
 //! - Base objects
+//!
+//! Some stdlib modules are implemented here, but most of them are in the `rustpython-stdlib` module. The
 
 // to allow `mod foo {}` in foo.rs; clippy thinks this is a mistake/misunderstanding of
 // how `mod` works, but we want this sometimes for pymodule declarations
diff --git a/vm/src/object/core.rs b/vm/src/object/core.rs
@@ -1,14 +1,14 @@
 //! Essential types for object models
 //!
-//! +-------------------------+--------------+---------------+
-//! |       Management        |    Typed     |    Untyped    |
-//! +-------------------------+--------------+---------------+
-//! | Interpreter-independent | Py<T>        | PyObject      |
-//! | Reference-counted       | PyRef<T>     | PyObjectRef   |
-//! | Weak                    | PyWeakRef<T> | PyRef<PyWeak> |
-//! +-------------------------+--------------+---------------+
+//! +-------------------------+--------------+-----------------------+
+//! |       Management        |       Typed      |      Untyped      |
+//! +-------------------------+------------------+-------------------+
+//! | Interpreter-independent | [`Py<T>`]        | [`PyObject`]      |
+//! | Reference-counted       | [`PyRef<T>`]     | [`PyObjectRef`]   |
+//! | Weak                    | [`PyWeakRef<T>`] | [`PyRef<PyWeak>`] |
+//! +-------------------------+--------------+-----------------------+
 //!
-//! PyRef<PyWeak> may looking like to be called as PyObjectWeak by the rule,
+//! [`PyRef<PyWeak>`] may looking like to be called as PyObjectWeak by the rule,
 //! but not to do to remember it is a PyRef object.
 use super::{
     PyAtomicRef,
diff --git a/vm/src/object/traverse.rs b/vm/src/object/traverse.rs
@@ -17,16 +17,16 @@ pub trait MaybeTraverse {
     fn try_traverse(&self, traverse_fn: &mut TraverseFn<'_>);
 }
 
-/// Type that need traverse it's children should impl `Traverse`(Not `MaybeTraverse`)
+/// Type that need traverse it's children should impl [`Traverse`] (not [`MaybeTraverse`])
 /// # Safety
-/// Please carefully read [`traverse()`] and follow the guideline
+/// Please carefully read [`Traverse::traverse()`] and follow the guideline
 pub unsafe trait Traverse {
     /// impl `traverse()` with caution! Following those guideline so traverse doesn't cause memory error!:
     /// - Make sure that every owned object(Every PyObjectRef/PyRef) is called with traverse_fn **at most once**.
     ///   If some field is not called, the worst results is just memory leak,
     ///   but if some field is called repeatedly, panic and deadlock can happen.
     ///
-    /// - _**DO NOT**_ clone a `PyObjectRef` or `PyRef<T>` in `traverse()`
+    /// - _**DO NOT**_ clone a [`PyObjectRef`] or [`PyRef<T>`] in [`Traverse::traverse()`]
     fn traverse(&self, traverse_fn: &mut TraverseFn<'_>);
 }
 
diff --git a/vm/src/prelude.rs b/vm/src/prelude.rs
@@ -1,3 +1,7 @@
+//! The prelude imports the various objects and traits.
+//!
+//! The intention is that one can include `use rustpython_vm::prelude::*`.
+
 pub use crate::{
     object::{
         AsObject, Py, PyExact, PyObject, PyObjectRef, PyPayload, PyRef, PyRefExact, PyResult,
diff --git a/vm/src/protocol/buffer.rs b/vm/src/protocol/buffer.rs
@@ -1,5 +1,5 @@
 //! Buffer protocol
-//! https://docs.python.org/3/c-api/buffer.html
+//! <https://docs.python.org/3/c-api/buffer.html>
 
 use crate::{
     Py, PyObject, PyObjectRef, PyPayload, PyRef, PyResult, TryFromBorrowedObject, VirtualMachine,
diff --git a/vm/src/protocol/object.rs b/vm/src/protocol/object.rs
@@ -1,5 +1,5 @@
 //! Object Protocol
-//! https://docs.python.org/3/c-api/object.html
+//! <https://docs.python.org/3/c-api/object.html>
 
 use crate::{
     AsObject, Py, PyObject, PyObjectRef, PyResult, TryFromObject, VirtualMachine,
diff --git a/vm/src/readline.rs b/vm/src/readline.rs
@@ -1,3 +1,8 @@
+//! Readline interface for REPLs
+//!
+//! This module provides a common interface for reading lines from the console, with support for history and completion.
+//! It uses the [`rustyline`] crate on non-WASM platforms and a custom implementation on WASM platforms.
+
 use std::{io, path::Path};
 
 type OtherError = Box<dyn std::error::Error>;
diff --git a/vm/src/suggestion.rs b/vm/src/suggestion.rs
@@ -1,3 +1,6 @@
+//! This module provides functionality to suggest similar names for attributes or variables.
+//! This is used during tracebacks.
+
 use crate::{
     AsObject, Py, PyObjectRef, VirtualMachine,
     builtins::{PyStr, PyStrRef},
diff --git a/vm/src/version.rs b/vm/src/version.rs
@@ -1,5 +1,4 @@
-/* Several function to retrieve version information.
- */
+//! Several function to retrieve version information.
 
 use chrono::{Local, prelude::DateTime};
 use std::time::{Duration, UNIX_EPOCH};
diff --git a/vm/src/vm/interpreter.rs b/vm/src/vm/interpreter.rs
@@ -64,21 +64,20 @@ impl Interpreter {
     ///
     /// To finalize the vm once all desired `enter`s are called, calling `finalize` will be helpful.
     ///
-    /// See also [`run`] for managed way to run the interpreter.
+    /// See also [`Interpreter::run`] for managed way to run the interpreter.
     pub fn enter<F, R>(&self, f: F) -> R
     where
         F: FnOnce(&VirtualMachine) -> R,
     {
         thread::enter_vm(&self.vm, || f(&self.vm))
     }
 
-    /// Run [`enter`] and call `expect_pyresult` for the result.
+    /// Run [`Interpreter::enter`] and call [`VirtualMachine::expect_pyresult`] for the result.
     ///
     /// This function is useful when you want to expect a result from the function,
     /// but also print useful panic information when exception raised.
     ///
-    /// See [`enter`] for more information.
-    /// See [`expect_pyresult`] for more information.
+    /// See also [`Interpreter::enter`] and [`VirtualMachine::expect_pyresult`] for more information.
     pub fn enter_and_expect<F, R>(&self, f: F, msg: &str) -> R
     where
         F: FnOnce(&VirtualMachine) -> PyResult<R>,
@@ -92,11 +91,11 @@ impl Interpreter {
     /// Run a function with the main virtual machine and return exit code.
     ///
     /// To enter vm context only once and safely terminate the vm, this function is preferred.
-    /// Unlike [`enter`], `run` calls finalize and returns exit code.
+    /// Unlike [`Interpreter::enter`], `run` calls finalize and returns exit code.
     /// You will not be able to obtain Python exception in this way.
     ///
-    /// See [`finalize`] for the finalization steps.
-    /// See also [`enter`] for pure function call to obtain Python exception.
+    /// See [`Interpreter::finalize`] for the finalization steps.
+    /// See also [`Interpreter::enter`] for pure function call to obtain Python exception.
     pub fn run<F>(self, f: F) -> u8
     where
         F: FnOnce(&VirtualMachine) -> PyResult<()>,
diff --git a/vm/src/vm/mod.rs b/vm/src/vm/mod.rs
@@ -61,7 +61,7 @@ pub const MAX_MEMORY_SIZE: usize = isize::MAX as usize;
 /// Top level container of a python virtual machine. In theory you could
 /// create more instances of this struct and have them operate fully isolated.
 ///
-/// To construct this, please refer to the [`Interpreter`](Interpreter)
+/// To construct this, please refer to the [`Interpreter`]
 pub struct VirtualMachine {
     pub builtins: PyRef<PyModule>,
     pub sys_module: PyRef<PyModule>,
@@ -564,7 +564,7 @@ impl VirtualMachine {
     /// Call Python __import__ function without from_list.
     /// Roughly equivalent to `import module_name` or `import top.submodule`.
     ///
-    /// See also [`import_from`] for more advanced import.
+    /// See also [`VirtualMachine::import_from`] for more advanced import.
     /// See also [`rustpython_vm::import::import_source`] and other primitive import functions.
     #[inline]
     pub fn import<'a>(&self, module_name: impl AsPyStr<'a>, level: usize) -> PyResult {
diff --git a/vm/src/vm/vm_ops.rs b/vm/src/vm/vm_ops.rs
@@ -152,9 +152,9 @@ impl VirtualMachine {
     /// Calling scheme used for binary operations:
     ///
     /// Order operations are tried until either a valid result or error:
-    ///   b.rop(b,a)[*], a.op(a,b), b.rop(b,a)
+    ///   `b.rop(b,a)[*], a.op(a,b), b.rop(b,a)`
     ///
-    /// [*] only when Py_TYPE(a) != Py_TYPE(b) && Py_TYPE(b) is a subclass of Py_TYPE(a)
+    /// `[*]` - only when Py_TYPE(a) != Py_TYPE(b) && Py_TYPE(b) is a subclass of Py_TYPE(a)
     pub fn binary_op1(&self, a: &PyObject, b: &PyObject, op_slot: PyNumberBinaryOp) -> PyResult {
         let class_a = a.class();
         let class_b = b.class();
diff --git a/wtf8/src/lib.rs b/wtf8/src/lib.rs
@@ -19,7 +19,7 @@
 //!
 //! We use WTF-8 over something more similar to CPython's string implementation
 //! because of its compatibility with UTF-8, meaning that in the case where a
-//! string has no surrogates, it can be viewed as a UTF-8 Rust [`str`] without
+//! string has no surrogates, it can be viewed as a UTF-8 Rust [`prim@str`] without
 //! needing any copies or re-encoding.
 //!
 //! This implementation is mostly copied from the WTF-8 implementation in the

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-//! This module is modified from tokio::util::linked_list: https://github.com/tokio-rs/tokio/blob/master/tokio/src/util/linked_list.rs`
	`1`	`+//! This module is modified from tokio::util::linked_list: <https://github.com/tokio-rs/tokio/blob/master/tokio/src/util/linked_list.rs>`
`2`	`2`	`//! Tokio is licensed under the MIT license:`
`3`	`3`	`//!`
`4`	`4`	`//! Copyright (c) 2021 Tokio Contributors`
Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,11 @@ pub enum RunMode {`
`13`	`13`	`}`
`14`	`14`
`15`	`15`	`pub enum InstallPipMode {`
	`16`	`+ /// Install pip using the ensurepip pip module. This has a higher chance of`
	`17`	`+ /// success, but may not install the latest version of pip.`
`16`	`18`	`Ensurepip,`
	`19`	`+ /// Install pip using the get-pip.py script, which retrieves the latest pip version.`
	`20`	`+ /// This can be broken due to incompatibilities with cpython.`
`17`	`21`	`GetPip,`
`18`	`22`	`}`
`19`	`23`
Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,7 @@ fn shell_exec(`
`71`	`71`	`}`
`72`	`72`	`}`
`73`	`73`
	`74`	`+/// Enter a repl loop`
`74`	`75`	`pub fn run_shell(vm: &VirtualMachine, scope: Scope) -> PyResult<()> {`
`75`	`76`	`let mut repl = Readline::new(helper::ShellHelper::new(vm, scope.globals.clone()));`
`76`	`77`	`let mut full_input = String::new();`
Original file line number	Diff line number	Diff line change
`@@ -65,7 +65,7 @@ const fn zst_ref_out_of_thin_air<T: 'static>(x: T) -> &'static T {`
`65`	`65`	`}`
`66`	`66`	`}`
`67`	`67`
`68`		-/// Get the [`STATIC_FUNC`](IntoPyNativeFn::STATIC_FUNC) of the passed function. The same
	`68`	`+/// Get the STATIC_FUNC of the passed function. The same`
`69`	`69`	`/// requirements of zero-sizedness apply, see that documentation for details.`
`70`	`70`	`///`
`71`	`71`	/// Equivalent to [`IntoPyNativeFn::into_func()`], but usable in a const context. This is only