Ранее у меня был api, в котором было множество функций, все из которых ожидали карту в очень конкретном формате. Когда дело дошло до документирования этого API, я обнаружил, что в docstrings каждой из этих функций я повторял "Карта, с которой эта функция вызывается, должна иметь такой и такой формат, и это поле карты означает такое-то."
Итак, я подумал, что для этих функций будет лучше взять запись, и я мог бы просто документировать запись. Однако, как представляется, невозможно документировать записи, по крайней мере, интерпретироваться либо макросом doc
, либо маргинальным.
Предлагаемое решение здесь означает "просто добавьте ключ: doc в метаданные записи".
Я попробовал (defrecord ^{:doc "Here is some documentation"} MyRecord [field1 field2])
, но макрорасширение это говорит о том, что это не имеет никакого эффекта. Также defrecord
возвращает экземпляр java.lang.class
, который не реализует IMeta, поэтому я не уверен, что мы можем дать ему метаданные?
- Как документировать документы?
- Здесь записано подходящее решение?