警告"doc注释不被rustdoc使用“意味着什么，我如何修复它？

Question

以下代码在编译时会产生警告：

pub fn add_source_path(request: &mut Request) -> IronResult<Response> {
/// Adds source path to the database.
///
/// This function saves provided absolute path (on the server) to the database
/// and goes over all jpeg files recursively in order to add them to DB.

let params = request.get_ref::<Params>().unwrap();

let path = &params["path"];

这是一个警告：

warning: doc comment not used by rustdoc
--> src/crawler.rs:64:2
   |
64 |  /// Adds source path to the database.
   |  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: #[warn(unused_doc_comment)] on by default

这个警告究竟意味着什么，以及如何修正它？

Answer 1

以///开头的注释用于生成文档。这些文档注释在它们记录的功能之前。引用https://doc.rust-lang.org/book/second-edition/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments

将文档注释放在他们正在记录的项目之前。

/// Adds source path to the database.
///
/// This function saves provided absolute path (on the server) to the database
/// and goes over all jpeg files recursively in order to add them to DB.
pub fn add_source_path(request: &mut Request) -> IronResult<Response> {
    // ...
}