Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs within defrecord #145

Open
atroche opened this issue Jan 16, 2015 · 6 comments
Open

Docs within defrecord #145

atroche opened this issue Jan 16, 2015 · 6 comments

Comments

@atroche
Copy link

atroche commented Jan 16, 2015

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
Copy link
Collaborator

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
Copy link
Author

atroche commented Jan 16, 2015

(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.

screen shot 2015-01-16 at 12 38 37 pm

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

@benjamin-bader
Copy link
Collaborator

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
Copy link
Author

atroche commented Jan 16, 2015

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
Copy link
Author

atroche commented Jan 16, 2015

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]))

clj-zendesk_--_marginalia

@benjamin-bader
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants