[Open source, Программирование, Системное программирование, Компиляторы, Rust] Rust 1.48.0: упрощение создания ссылок и псевдонимы поиска (перевод)

Ответить на тему

Автор

Сообщение

news_bot ^®

Стаж: 6 лет 9 месяцев
Сообщений: 27286

news_bot ^® написал(а)
20-Ноя-2020 17:30

Цитировать

Команда 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:

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

Смотрите подробные примечания к выпуску для более детальной информации.
Другие изменения
Синтаксис, пакетный менеджер Cargo и анализатор Clippy также претерпели некоторые изменения.
Участники 1.48.0
Множество людей собрались вместе, чтобы создать Rust 1.48.0. Мы не смогли бы сделать это без всех вас. Спасибо!
От переводчиков
С любыми вопросами по языку Rust вам смогут помочь в русскоязычном Телеграм-чате или же в аналогичном чате для новичковых вопросов. Если у вас есть вопросы по переводам или хотите помогать с ними, то обращайтесь в чат переводчиков.
Так же можете поддержать нас на opencollective: https://opencollective.com/rust-lang-ru.
Данную статью совместными усилиями перевели Belanchuk, andreevlex и funkill.
===========
Источник:
habr.com
===========
===========
Автор оригинала: The Rust Release Team
===========Похожие новости:

Теги для поиска: #_open_source, #_programmirovanie (Программирование), #_sistemnoe_programmirovanie (Системное программирование), #_kompiljatory (Компиляторы), #_rust, #_clippy, #_cargo, #_rustc, #_rustdoc, #_rustfmt, #_rustfix, #_release, #_stable, #_jazyki_programmirovanija (языки программирования), #_stabilnaja_versija (стабильная версия), #_vypusk_versij (выпуск версий), #_sistemnoe_programmirovanie (системное программирование), #_novosti_tehnologij (новости технологий), #_perevod (перевод), #_open_source, #_programmirovanie (
Программирование
), #_sistemnoe_programmirovanie (
Системное программирование
), #_kompiljatory (
Компиляторы
), #_rust

Профиль ЛС

Ответить на тему

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 22-Ноя 16:19
Часовой пояс: UTC + 5