The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]



Вариант для распечатки  
Пред. тема | След. тема 
Форум Разговоры, обсуждение новостей
Режим отображения отдельной подветви беседы [ Отслеживать ]

Оглавление

Выпуск языка программирования Rust 1.54, opennews (??), 29-Июл-21, (0) [смотреть все]

Сообщения [Сортировка по времени | RSS]


10. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Аноньимъ (ok), 29-Июл-21, 22:35 
>Вызов макросов внутри атрибутов может оказаться полезным для включения в документирующие комментарии содержимого из других файлов. Например, для вставки содержимого файла README и результата выполнения скрипта можно указать

Что-то я непронял совсем что тут происходит и зачем это нужно.
Макрос в коде меняет файл с кодом или что тут происходит?

Ответить | Правка | Наверх | Cообщить модератору

19. "Выпуск языка программирования Rust 1.54"  –1 +/
Сообщение от Dzen Python (ok), 29-Июл-21, 22:45 
Мне больше интересно, зачем вставлять в .rs файл содержимое .md файла.

Стандартный хедер "этот файл под лиценцией {0}, писан {1}, email {2}" может вставить даже не самая продвинутая IDE. Далее по идее ридми.тхт и комментарии должны наоборот, из src-файлов ИЗвлекаться, и на их основе генерироваться нормальная человеческая документация + файл ридми.

Также мне реально стало интересно, зачем пихать в .rs файл вывод .[скрипт].

Вот тут действительно, непонятно. Хотелось бы увидеть хотя бы три сценария использования, где это не натягивание совы на глобус, а глобуса - в попугая

Ответить | Правка | Наверх | Cообщить модератору

21. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Аноньимъ (ok), 29-Июл-21, 22:48 
> Далее по идее ридми.тхт и комментарии должны наоборот, из src-файлов ИЗвлекаться, и на их основе генерироваться нормальная человеческая документация + файл ридми.

Вот и я раньше так думал, а теперь не понимаю что происходит. Может нам опытные растенианци объяснят.

Ответить | Правка | Наверх | Cообщить модератору

420. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Аноним (-), 30-Июл-21, 19:37 
>Может нам опытные растенианци объяснят.

Растаманы - это растения? Растаман - это овощь?

Ответить | Правка | Наверх | Cообщить модератору

53. "Выпуск языка программирования Rust 1.54"  +5 +/
Сообщение от ПомидорИзДолины (?), 29-Июл-21, 23:23 
В Расте документация генерируется на основе специально оформленных комментариев (doxigen вид сбоку). Когда документации становится много это усложняет навигацию по исходному когда.

Теперь часть документации можно вынести в отдельные файлы, а в исходниках остваить только краткую выжимку.

Ответить | Правка | К родителю #19 | Наверх | Cообщить модератору

188. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Аноньимъ (ok), 30-Июл-21, 03:57 
Но зачем для этого какие-то макросы в исходниках? В доках пишешь имя функции и комментарий.

Или я чего-то не понимаю?

Ответить | Правка | Наверх | Cообщить модератору

200. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Анонимъ (?), 30-Июл-21, 04:19 
Комментарии-документация чисто технически являются специальным синтаксисом для #[doc] макроса.
Ответить | Правка | Наверх | Cообщить модератору

210. "Выпуск языка программирования Rust 1.54"  +4 +/
Сообщение от Аноньимъ (ok), 30-Июл-21, 04:35 
Я к тому что.
1 Доки собираются из исходников.
2 В исходниках слишком много доков, вынесем их в отдельный файл. Чтобы... Чтобы линковать отдельный файл в исходники откуда собирать доки?

Почему бы не собирать доки сразу из отдельного файла с доками?
Зачем в исходники то тянуть что попало из каких-то файлов?

Или я всё неправильно понимаю?

Ответить | Правка | Наверх | Cообщить модератору

229. "Выпуск языка программирования Rust 1.54"  +2 +/
Сообщение от Анонимъ (?), 30-Июл-21, 05:29 
https://doc.rust-lang.org/std/pin/index.html

Вот пример выше. Подобную документацию удобнее держать рядом с кодом.

Ну или https://docs.rs/legion/0.4.0/legion/index.html в качестве случайного примера.

В дополнение: примеры кода в документации являются полноправными тестами (выполняются по cargo test).

Там подкрутили, здесь сделали удобнее, вон там ещё затюнили маленько. Мелочи, но по совокупности получаем одну из самых лучших документаций в индустрии. По крайней мере у крейтов, которые используют больше чем 1.5 землекопа.

Ответить | Правка | Наверх | Cообщить модератору

246. "Выпуск языка программирования Rust 1.54"  +4 +/
Сообщение от Аноним (246), 30-Июл-21, 06:39 
> примеры кода в документации являются полноправными тестами (выполняются по cargo test)

Особенно удобно, если это пример кода к какому-нибудь std::fs::remove_dir_all :)

Ответить | Правка | Наверх | Cообщить модератору

452. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Анонимъ (?), 30-Июл-21, 22:38 
Для таких случаев есть no_run.
Ответить | Правка | Наверх | Cообщить модератору

547. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Аноним (547), 31-Июл-21, 23:16 
Да это понятно :-) Просто не люблю такое неявное поведение.
Мне видится более разумным явное указание того, что пример кода является одновременно и тестом, чем такая инвертированная логика.
Ответить | Правка | Наверх | Cообщить модератору

455. "Выпуск языка программирования Rust 1.54"  +1 +/
Сообщение от Аноним (-), 30-Июл-21, 23:15 
>> примеры кода в документации являются полноправными тестами (выполняются по cargo test)
> Особенно удобно, если это пример кода к какому-нибудь std::fs::remove_dir_all :)

Ага, и то ли дело "make test" или ./configure_портянка_на_пару_тысяч_строк - там такое ну абсолютно невозможно!

> Суть проблемы в том, что в файле install.sh для очистки локальной копии собранных файлов вместо команды "rm -r yd-tools/usr" по ошибке была добавлена строка "rm -r /usr". Проблема появилась в коде 20 мая в ходе переработки сборочных скриптов и была исправлена несколько часов назад

Ой!

Ответить | Правка | К родителю #246 | Наверх | Cообщить модератору

263. "Выпуск языка программирования Rust 1.54"  +1 +/
Сообщение от n00by (ok), 30-Июл-21, 08:30 
> Почему бы не собирать доки сразу из отдельного файла с доками?
> Зачем в исходники то тянуть что попало из каких-то файлов?

Потому что процесс под названием "комментировать код" является приёмом реверс-инженерии. Когда разработка прямая, сначала формулируются требования к коду, а потом уже сам код. Когда требования и код расположены рядом, проще сохранять их соответствие. Таким образом возникли doxygen и подобные системы. Потом уже в них добавили опцию "вот этот файлик хорошо бы целиком включить в документацию".

Ответить | Правка | К родителю #210 | Наверх | Cообщить модератору

350. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Аноньимъ (ok), 30-Июл-21, 15:56 
Это логично, однако.
Комментировать код, и иметь отдельный файл для хранения документации, друг другу не противоречащие вещи.

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

Понятно если к такой системе пришли эволюционно и постепенно.
Но было ли абсолютно необходимо для раста набивать все шишки прошлых поколений, вопрос открытый.

И мы так и не выяснили что за выход какого скрипта нужно подключать в исходный код этим макросом.

Ответить | Правка | Наверх | Cообщить модератору

363. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от n00by (ok), 30-Июл-21, 16:21 
Документация ведь делится на несколько уровней. Есть и краткое описание проекта (почти не меняется и к какому-то конкретному фрагменту кода не привязана), информация об авторе, лицензии и т.п. Вот пример титульной страницы документации на Доксиген, наверняка в отдельном файле https://www.doxygen.nl/index.html
Ответить | Правка | Наверх | Cообщить модератору

46. "Выпуск языка программирования Rust 1.54"  +/
Сообщение от Аноним (46), 29-Июл-21, 23:14 
В cargo doc появилась поддержка не только api документации, поэтому теперь не обязательно нужен дополнительный тулинг, чтобы писать гайды, туториалы и проч подобные вещи.
Ответить | Правка | К родителю #10 | Наверх | Cообщить модератору

240. "Выпуск языка программирования Rust 1.54"  –3 +/
Сообщение от псевдонимус (?), 30-Июл-21, 06:13 
Тут происходит Чад кутежа во мгле ада.

Это раст, парень!

Ответить | Правка | К родителю #10 | Наверх | Cообщить модератору

Архив | Удалить

Рекомендовать для помещения в FAQ | Индекс форумов | Темы | Пред. тема | След. тема




Партнёры:
PostgresPro
Inferno Solutions
Hosting by Hoster.ru
Хостинг:

Закладки на сайте
Проследить за страницей
Created 1996-2024 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру