Документирование предметов не видны

Question

Я заметил, что плагины компилятора часто предоставляют макросы, которые в документации даже не упоминаются. Они зарегистрированы и созданы программно, а не определены в синтаксисе, который распознает rustdoc. Естественно, никакая документация не может быть показана.

Я ищу способ обойти это, какой-то способ создания документации для макроса, который не существует в ящике во время компиляции.

Я заметил, что синтаксический ящик мог бы извлечь выгоду из такой вещи. quote_itemнапример, полностью без документов. Я даже не могу найти код, который его регистрирует.

Answer 1

Одна возможность состоит в том, чтобы сделать то, что делает компилятор: создать пустой macro_rules! макрос и приложить к этому документацию. Например, если ящик определяет foo который принимает одно выражение, а затем написать что-то вроде

/// Documentation
#[macro_export]
macro_rules! foo {
     ($e: expr) => ({ /* syntax extension */ })
}

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

Вы можете искать источник Rust дляquote_item, что полезно по двум причинам: оно дает несколько примеров, а также позволяет отследить определение. Последнее проще с использованием экземпляра Rust DXR, который может искать вещи с кавычками (то есть может находить строки) и включает в себя различные приемы навигации по исходному коду (например, переход к определению).