clojure içindeki kayıtların belgelenmesi

Question

Daha önce çok sayıda biçimde bir işlevi olan bir api'ye sahiptim, hepsi çok özel bir biçimde bir harita bekleniyordu. Bu API'yi belgelemeye gelince, bu fonksiyonların her birinin belgeselinde tekrarlıyorum “Bu fonksiyonun çağrıldığı harita böyle bir formatta olmalı ve harita bu alan ve benzeri ."

Bu yüzden bu fonksiyonlar rekor almak için daha iyi ve sadece yerine kayıt belgelemek olabilir düşündüm. Ancak, en azından doc makrosu veya Marginalia tarafından yorumlanan kayıtların belgelenmesi mümkün görünmemektedir.

bir çözüm ": kaydın meta doc anahtarı sadece eklemek" olduğunu here önerdi.

Ben (defrecord ^{:doc "Here is some documentation"} MyRecord [field1 field2]) çalıştı ama macroexpanding bu herhangi bir etkisi yoktur göstermektedir. Ayrıca defrecord, IMeta'yı uygulamayan bir java.lang.class örneğini döndürür; bu nedenle meta verilere verebileceğimizden emin değilim?

• nasıl kayıtları dokümante edilmelidir?
• Burada uygun bir çözüm kayıtları var mı?

Answer 1

TL; DR: Ne yazık ki yapamazsınız. docs itibaren

:

Semboller ve tahsilat desteği meta

kullandığınız

defrecord aslında bir java sınıfı yaratıyor. Sınıflar ne semboller ne de Clojure olduğu için, bunlara belge ekleyemezsiniz. Kayıtlara meta eklenecek neden onun mümkün değildir

Daha detaylı açıklama

aşağıdaki REPL oturumu gösterir.

user=> (defrecord A [a b]) 
#<Class@61f53f0e user.A> 
user=> (meta A) ;; <= A contains no metadata 
nil 

Burada dikkat edilmesi gereken önemli nokta, A'nın normal bir java sınıfı olmasıdır. Eğer A meta ayarlamaya çalışırsanız Eğer

user=> (with-meta A {:doc "Hello"}) 

ClassCastException java.lang.Class cannot be cast to clojure.lang.IObj 

Görünüşe ile-meta bir clojure.lang.IObj beklediğini ilginç bir hata iletisi alır. java.lang.Class bir Javaland yapısı olduğundan, clojure.lang.IObj hiçbir şeyden haberi yoktur.

bu yöntem yoktur açıkça kaydeden withMeta nesne olması x bekliyor Gördüğünüz gibi en with-meta

user=> (source with-meta) 
(def 
^{:arglists '([^clojure.lang.IObj obj m]) 
    :doc "Returns an object of the same type and value as obj, with 
    map m as its metadata." 
    :added "1.0" 
    :static true} 
with-meta (fn ^:static with-meta [^clojure.lang.IObj x m] 
      (. x (withMeta m)))) 

için kaynak kodu ile hemen bakalım.