Rust 1.48.0: упрощение создания ссылок и псевдонимы поиска

Команда Rust рада сообщить о выпуске новой версии, 1.48.0. Rust — это язык программирования, позволяющий каждому создавать надёжное и эффективное программное обеспечение.

Если вы установили предыдущую версию Rust средствами rustup, то для обновления до версии 1.48.0 вам достаточно выполнить следующую команду:

rustup update stable

Если у вас ещё не установлен rustup, вы можете установить его с соответствующей страницы нашего веб-сайта, а также посмотреть подробные примечания к выпуску на GitHub.

Что вошло в стабильную версию 1.48.0

Звездой этого выпуска стал rustdoc с изменениями, облегчающими написание документации! Смотрите подробные примечания к выпуску, чтобы узнать о других изменениях, не представленных в данном анонсе.

Упрощение создания ссылок в rustdoc

rustdoc — инструмент для документирования библиотек, включённый в поставку Rust, позволяет вам писать документацию используя Markdown. Это делает его простым в использовании, но есть и неприятные моменты. Допустим вы пишете документацию для некоторого кода на Rust, который выглядит подобным образом:

pub mod foo {
    pub struct Foo;
}

pub mod bar {
    pub struct Bar;
}

У нас есть два модуля, каждый их которых содержит в себе структуру. Предположим, что мы хотим использовать эти две структуры вместе, а значит мы должны указать это в документации. Соответственно, мы должны написать что-то вроде этого:

pub mod foo {
    /// Некоторая документация для `Foo`
    ///
    /// Вы можете захотеть использовать `Foo` и `Bar` вместе.
    pub struct Foo;
}

pub mod bar {
    /// Какая-то документация  `Bar`
    ///
    /// Вы можете захотеть использовать `Bar` и `Foo` вместе.
    pub struct Bar;
}

Всё выглядит хорошо, но было бы замечательно, если бы у нас была ссылка на другой тип. Пользователям нашей библиотеки было бы удобно переходить между ними в нашей документации.

Проблемой здесь является то, что Markdown не знает ничего о Rust и о ссылках, генерируемых rustdoc. Из-за этого программистам на Rust приходится писать эти ссылки самостоятельно:

pub mod foo {
    /// Некоторая документация для `Foo`
    ///
    /// Вы можете захотеть использовать `Foo` и [`Bar`] вместе.
    ///
    /// [`Bar`]: ../bar/struct.Bar.html
    pub struct Foo;
}

pub mod bar {
    /// Какая-то документация  `Bar`
    ///
    /// Вы можете захотеть использовать `Bar` и [`Foo`] вместе.
    ///
    /// [`Foo`]: ../foo/struct.Foo.html
    pub struct Bar;
}

Обратите внимание, что мы используем относительные ссылки, так что документация будет работать и в оффлайне. Этот процесс не только утомительный и подверженный ошибкам, но и иногда ошибочен. Если мы поместим pub use bar::Bar в корне нашего пакета, чтобы реэкспортировать Bar в корень, мы получим ошибку в ссылках. Но если мы исправим её так, то она будет не правильна для структуры Bar из модуля. Вы не можете написать эту ссылку вручную и сделать так, чтобы она везде была точной.

Начиная с этого выпуска, вы можете использовать специальный синтаксис, чтобы дать понять rustdoc, что ваша ссылка указывает на тип, и он сгенерирует для него правильную ссылку. Посмотрите примеры, основанные на нашем предыдущем коде:

pub mod foo {
    /// Некоторая документация для `Foo`
    ///
    /// Вы можете захотеть использовать `Foo` и [`Bar`](crate::bar::Bar) вместе.
    pub struct Foo;
}

pub mod bar {
    /// Какая-то документация  `Bar`
    ///
    /// Вы можете захотеть использовать `Bar` и [`crate::foo::Foo`] вместе.
    pub struct Bar;
}

Первый пример показывает такой же текст, как и раньше, но генерирует правильную ссылку на тип Bar. Второй — ссылается на Foo, но показывает весь путь crate::foo::Foo как текст ссылки.

Здесь вы можете использовать несколько вариантов. Пожалуйста, посмотрите дополнительную информацию в главе "Linking to items by name" книги по rustdoc. Также есть пост в блоге "Inside Rust" рассказывающий историю этой функциональности, написанный участниками, реализовавшими её!

Добавление псевдонимов поиска

Теперь вы можете добавить #[doc(alias = "<alias>")] чтобы при поиске через пользовательский интерфейс rustdocможно было искать по псевдониму. Это небольшое, но очень полезное изменение. Оно выглядит следующим образом:

#[doc(alias = "bar")]
struct Foo;

С такой аннотацией, если мы введём "bar" в строку поиска rustdoc, одним из результатов будет Foo, хоть и поисковый запрос не содержит "Foo".

Интересным вариантом использования являются пакеты FFI-адаптеров, где каждая функция Rust может ссылаться на адаптируемую C функцию. Пользователи, использующие библиотеку на C, могут с лёгкостью найти нужную функцию на Rust!

Изменения в стандартной библиотеке

Наиболее значимым изменением в стандартной библиотеке можно назвать стабилизацию [T; N]: TryFrom<Vec<T>>. Что это значит? Вы можете использовать это когда пытаетесь преобразовать вектор в массив с заданной длиной:

use std::convert::TryInto;

let v1: Vec<u32> = vec![1, 2, 3];

// Это пройдёт успешно: наш вектор имеет длину 3 и мы пытаемся преобразовать
// его в массив из трех элементов.
let a1: [u32; 3] = v1.try_into().expect("неправильная длина");

// Но если мы попытаемся сделать это с вектором из 5 элементов...
let v2: Vec<u32> = vec![1, 2, 3, 4, 5];

// ... наш код запаникует из-за того, что мы используем неправильную длину.
let a2: [u32; 3] = v2.try_into().expect("неправильная длина");

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

Дополнительно в этом выпуске были стабилизированы пять новых API:

• slice::as_ptr_range
• slice::as_mut_ptr_range
• VecDeque::make_contiguous
• future::pending
• future::ready

Следующие ранее стабилизированные API стали const:

• Option::is_some
• Option::is_none
• Option::as_ref
• Result::is_ok
• Result::is_err
• Result::as_ref
• Ordering::reverse
• Ordering::then

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

Другие изменения

Синтаксис, пакетный менеджер Cargo и анализатор Clippy также претерпели некоторые изменения.

Участники 1.48.0

Множество людей собрались вместе, чтобы создать Rust 1.48.0. Мы не смогли бы сделать это без всех вас. Спасибо!

От переводчиков

С любыми вопросами по языку Rust вам смогут помочь в русскоязычном Телеграм-чате или же в аналогичном чате для новичковых вопросов. Если у вас есть вопросы по переводам или хотите помогать с ними, то обращайтесь в чат переводчиков.
Так же можете поддержать нас на opencollective: https://opencollective.com/rust-lang-ru.

Данную статью совместными усилиями перевели Belanchuk, andreevlex и funkill.