title: Documentation of records in clojure
body: <p>I previously had an api which had a number of functions in it, all of which expected a map in a very particular format. When it came to documenting this API, I found that in the docstrings of each of these functions I was repeating "The map with which this function is called must be of such and such a format, and this field of the map means such and such."</p>
  
  <p>So I thought it would be better for those functions to take a record, and that I could just document the record instead. However it doesn't seem to be possible to document records, at least in any way interpreted either by the <code>doc</code> macro or Marginalia.</p>
  
  <p>A solution suggested <a href="https://groups.google.com/forum/#!topic/clojure/_JQfH7kbKqk">here</a> is "just add a :doc key in the record's meta".</p>
  
  <p>I tried <code>(defrecord ^{:doc "Here is some documentation"} MyRecord [field1 field2])</code> but macroexpanding this suggests it doesn't have any effect. Also <code>defrecord</code> returns an instance of <code>java.lang.class</code> which doesn't implement IMeta so I'm not sure we can give it metadata?</p>
  
  <ul>
  <li>How should records be documented?</li>
  <li>Are records an appropriate solution here?</li>
  </ul>