Docs within defrecord

[atroche]

Hello! Is there a way to add docs for the method implementations in defrecord? Right now I just have a big block of comments before the defrecord expression, which is nowhere near as nice as having the docs for each method implementation side-by-side in the Marginalia output.

Any ideas?

[benjamin-bader]

This sounds like it may be a bug. Can you please paste a code snippet here showing your defrecord usage, along with a screenshot of the output?

[atroche]

(defrecord Resource
  [resource-name]
  StandardOperations

  (get-all [_]
  ;; a GET on the root of a resource (e.g. /api/v2/users.json)
    ((plural resource-name) (api-call :get (base-url resource-name))))
  (get-one [_ id]
  ;; a GET on a specific resource (e.g. /api/v2//users/3.json)
    ((singular resource-name) (api-call :get (str (base-url resource-name) "/%s") [id])))
  (create [_ data]
  ;; a POST on the root of a resource (e.g. /api/v2/users.json)
    ((singular resource-name) (api-call :post
                                        (base-url resource-name)
                                        nil
                                        {(singular resource-name) data})))
  (delete [_ id]
  ;; a DELETE on a specific resource (e.g. /api/v2//users/3.json)
    (api-call :delete (str (base-url resource-name) "/%s") [id])))

I've tried the comment under get-all at different levels of indentation.

As far as I can workout, defrecord doesn't allow docstrings anywhere.

[benjamin-bader]

I'm afraid that you're correct - defrecord and its protocol implementations don't seem to allow for docstrings (see https://groups.google.com/forum/#!topic/clojure/_JQfH7kbKqk). I don't think that there is special support for "should-be" docstrings, and would be hesitant to add support for a hack around Clojure's limitations.

Docstrings usually live in the protocol definition, e.g.

(defprotocol StandardOperations
  (get-all [self] "a GET on the root of a resource (e.g. /api/v2/users.json)")
  ;; etc
)

I haven't done much Clojure lately, so am possibly forgetting something relevant; as far as I recall, this works in marginalia currently.

[atroche]

Ah, thanks! I think what got me was the the docstring in defprotocol come
after the arguments vector, unlike everything else.

On 16 January 2015 at 12:51, Ben Bader notifications@github.com wrote:

Docstrings usually live in the protocol definition, e.g.

(defprotocol StandardOperations
(get-all [arg] "a GET on the root of a resource (e.g. /api/v2/users.json)")
;; etc
)

I'm afraid that you're correct - defrecord and its protocol
implementations don't seem to allow for docstrings (see
https://groups.google.com/forum/#!topic/clojure/_JQfH7kbKqk).

I haven't done much Clojure lately, so am possibly forgetting something
relevant; as far as I recall, this works in marginalia currently.

—
Reply to this email directly or view it on GitHub
#145 (comment).

-- Alistair

[atroche]

Hmm, seems like Marginalia still doesn't like it.

(defprotocol StandardOperations
  "Many resources have a standard range of things you can do with them (CRUD, basically)."
  (get-all [_] "a GET on the root of a resource (e.g. /api/v2/users.json)")
  (get-one [_ id])
  (create  [_ data])
  (update  [_ id data])
  (delete  [_ id]))

[benjamin-bader]

OK, that's certainly a problem. I'll keep this issue open to track it.

https://github.com/gdeer81/marginalia/blob/master/src/marginalia/parser.clj#L232 indicates that we at at least attempt to extract docstrings from protocol methods. I may be missing something, but it seems that we are not doing this properly. Thanks for the report.