Как сделать ссылку на другие fns/structs/enums/traits в rustdoc?

Я строю библиотеку Rust и хочу придать ей немного блеска. В Dustdoc я иногда хотел бы ссылаться на другие части библиотеки в документах, например fns, traitс или structs. Какой официальный синтаксис для этого?

Источник

4 ответа

Решение

Rustdoc кажется, генерирует в основном детерминированные имена файлов для составных элементов ящика. Поэтому, если у вас есть enum названный Complex вы можете вообще ссылаться на него используя:

[Complex](enum.Complex.html)

Точно так же struct называется Point будет выглядеть так:

[Point](struct.Point.html)

Это должно быть перенесено на большинство определений (fn, trait, и так далее).

Я должен отметить, что это может не работать в определенных ситуациях. Если по какой-либо причине файлы HTML, созданные rustdoc в конечном итоге на разных уровнях вложенности, относительные ссылки, которые я перечислил выше, могут 404, У меня еще не было этой проблемы.

Источник

RFC 1946 добавляет концепцию ссылок внутри документации. Это позволяет использовать пути Rust в качестве URL ссылки:

[Iterator](std::iter::Iterator)
[Iterator][iter], and somewhere else in the document: [iter]: std::iter::Iterator
[Iterator], and somewhere else in the document: [Iterator]: std::iter::Iterator

Эта функция еще не стабилизирована, но если вы создаете документацию с помощью ночной цепочки инструментов, она автоматически включается.

В качестве конкретного примера, этот исходный код:

//! Check out [ExampleStruct], especially [this
//! method](ExampleStruct::foo), but [the trait method][trait] is also
//! cool. There is also [an enum variant you can
//! use](nested::ExampleEnum::Beta).
//!
//! [trait]: ExampleTrait::bar

pub struct ExampleStruct;

impl ExampleStruct {
    pub fn foo(&self) {}
}

pub trait ExampleTrait {
    fn bar();
}

pub mod nested {
    pub enum ExampleEnum {
        Alpha,
        Beta,
    }
}

Производит эту документацию:

пример сгенерированной документации

В частности, этот HTML генерируется:

<p>Check out <a href="../doc_link_example/struct.ExampleStruct.html" title="ExampleStruct">ExampleStruct</a>, especially <a href="../doc_link_example/struct.ExampleStruct.html#method.foo">this method</a>, but <a href="../doc_link_example/trait.ExampleTrait.html#tymethod.bar">the trait method</a> is also cool. There is also <a href="../doc_link_example/nested/enum.ExampleEnum.html#Beta.v">an enum variant you can use</a>.</p>
Источник

Если кто-то хочет связать какую-то конкретную часть структуры, например, метод в той же структуре

[from_file](#method.from_file)

или если это в другой структуре

[from_file](struct.SafeAccount.html#method.from_file)
Источник

Поскольку документация написана на Markdown, просто используйте синтаксис Markdown для гиперссылок; т.е.

[anchor text](URL)

Кроме того, взгляните на это: https://doc.rust-lang.org/book/documentation.html

Источник

В Rust 1.49 каждую ночь это работает (стабильная версия 1.48 еще не выпущена):

  • [super::structs::WebApiResponse]
  • [mycrate::structs::WebApiResponse]

и т.п.

Читать здесь

Источник
Другие вопросы по тегам