The OpenNET Project / Index page

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



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

Оглавление

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

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


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ообщить модератору

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

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




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

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