Re: examples in doc strings
Hi, it was discussed before whether examples should go into the docstring. Or to an :examples metadata to be even executable at the repl. Some expressed the opinion that docstring should be short and that such additional documentation should go somewhere else. I don't remember what the outcome of the discussion was. Until this discussion is settled this site might help to scratch your itch: http://clojuredocs.org/clojure_core/clojure.core/defmethod. And you can help out there easily without CA and such. Sincerely Meikel -- You received this message because you are subscribed to the Google Groups Clojure group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
Re: examples in doc strings
Yeah, I've got a permanent clojuredocs tab open all the time, but still it would be nice to settle this discussion, as currently their are doc strings that require a google search or a look at the source to see what they mean though, which is not ideal. Many of us are happy to help if we can have a place to direct our energy. Using :examples metadata (or even having the examples somewhere on contrib) would be fine, as long as they can show up on the repl and in tools when you run (doc fn). -Jeff On Apr 8, 2:18 pm, Meikel Brandmeyer m...@kotka.de wrote: Hi, it was discussed before whether examples should go into the docstring. Or to an :examples metadata to be even executable at the repl. Some expressed the opinion that docstring should be short and that such additional documentation should go somewhere else. I don't remember what the outcome of the discussion was. Until this discussion is settled this site might help to scratch your itch:http://clojuredocs.org/clojure_core/clojure.core/defmethod. And you can help out there easily without CA and such. Sincerely Meikel -- You received this message because you are subscribed to the Google Groups Clojure group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
Re: examples in doc strings
Another option is to create a function which pulls examples from clojuredocs.org on the fly (it has an API) and displays them in the REPL. I made a proof-of-concept for this but using the now-defunct Clojure Examples Wiki: https://gist.github.com/470031. The utility of something like this would be limited if it wasn't included in clojure.core, of course. Justin On Apr 8, 9:27 am, Jeff Rose ros...@gmail.com wrote: Yeah, I've got a permanent clojuredocs tab open all the time, but still it would be nice to settle this discussion, as currently their are doc strings that require a google search or a look at the source to see what they mean though, which is not ideal. Many of us are happy to help if we can have a place to direct our energy. Using :examples metadata (or even having the examples somewhere on contrib) would be fine, as long as they can show up on the repl and in tools when you run (doc fn). -Jeff On Apr 8, 2:18 pm, Meikel Brandmeyer m...@kotka.de wrote: Hi, it was discussed before whether examples should go into the docstring. Or to an :examples metadata to be even executable at the repl. Some expressed the opinion that docstring should be short and that such additional documentation should go somewhere else. I don't remember what the outcome of the discussion was. Until this discussion is settled this site might help to scratch your itch:http://clojuredocs.org/clojure_core/clojure.core/defmethod. And you can help out there easily without CA and such. Sincerely Meikel -- You received this message because you are subscribed to the Google Groups Clojure group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
Re: examples in doc strings
Jark does exactly this: http://icylisper.in/jark/doc.html Regards, Shantanu On Apr 8, 8:45 pm, Justin Kramer jkkra...@gmail.com wrote: Another option is to create a function which pulls examples from clojuredocs.org on the fly (it has an API) and displays them in the REPL. I made a proof-of-concept for this but using the now-defunct Clojure Examples Wiki:https://gist.github.com/470031. The utility of something like this would be limited if it wasn't included in clojure.core, of course. Justin On Apr 8, 9:27 am, Jeff Rose ros...@gmail.com wrote: Yeah, I've got a permanent clojuredocs tab open all the time, but still it would be nice to settle this discussion, as currently their are doc strings that require a google search or a look at the source to see what they mean though, which is not ideal. Many of us are happy to help if we can have a place to direct our energy. Using :examples metadata (or even having the examples somewhere on contrib) would be fine, as long as they can show up on the repl and in tools when you run (doc fn). -Jeff On Apr 8, 2:18 pm, Meikel Brandmeyer m...@kotka.de wrote: Hi, it was discussed before whether examples should go into the docstring. Or to an :examples metadata to be even executable at the repl. Some expressed the opinion that docstring should be short and that such additional documentation should go somewhere else. I don't remember what the outcome of the discussion was. Until this discussion is settled this site might help to scratch your itch:http://clojuredocs.org/clojure_core/clojure.core/defmethod. And you can help out there easily without CA and such. Sincerely Meikel -- You received this message because you are subscribed to the Google Groups Clojure group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
Re: examples in doc strings
I will put in a plug for my much neglected postdoc
https://github.com/markmfredrickson/postdoc
This takes the :examples approach (though it namespaces it within
another map: metadata - :postdoc - {:examples ... :see-also
... }).
Some ways to focus your effort would be to start a project that
requires postdoc as a dependency and the provides (postdoc name stuff)
for all of clojure.core (perhaps getting a leg up by copying the
online examples). Another alternative might be a connection between
postdoc and the clojuredocs API.
I've been meaning to finish up postdoc and promote it more, but until
the academic term ends, I doubt I will have the time. But I should
have time to accept patches and push new versions to clojars, so feel
free to send me patches/pull requests.
-M
On Apr 8, 12:09 pm, Shantanu Kumar kumar.shant...@gmail.com wrote:
Jark does exactly this:
http://icylisper.in/jark/doc.html
Regards,
Shantanu
On Apr 8, 8:45 pm, Justin Kramer jkkra...@gmail.com wrote:
Another option is to create a function which pulls examples from
clojuredocs.org on the fly (it has an API) and displays them in the
REPL. I made a proof-of-concept for this but using the now-defunct
Clojure Examples Wiki:https://gist.github.com/470031.
The utility of something like this would be limited if it wasn't
included in clojure.core, of course.
Justin
On Apr 8, 9:27 am, Jeff Rose ros...@gmail.com wrote:
Yeah, I've got a permanent clojuredocs tab open all the time, but
still it would be nice to settle this discussion, as currently their
are doc strings that require a google search or a look at the source
to see what they mean though, which is not ideal. Many of us are
happy to help if we can have a place to direct our energy.
Using :examples metadata (or even having the examples somewhere on
contrib) would be fine, as long as they can show up on the repl and in
tools when you run (doc fn).
-Jeff
On Apr 8, 2:18 pm, Meikel Brandmeyer m...@kotka.de wrote:
Hi,
it was discussed before whether examples should go into the docstring.
Or to an :examples metadata to be even executable at the repl. Some
expressed the opinion that docstring should be short and that such
additional documentation should go somewhere else. I don't remember
what the outcome of the discussion was.
Until this discussion is settled this site might help to scratch your
itch:http://clojuredocs.org/clojure_core/clojure.core/defmethod. And
you can help out there easily without CA and such.
Sincerely
Meikel
--
You received this message because you are subscribed to the Google
Groups Clojure group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
