Re: usage examples in clojure api docs
It could also be be helpful to have links to mailing list discussions
or blog postings discussing the reasons for including a method in
Clojure or the tradeoffs in using one method vs. another. A few
examples:
seq?, sequential?
http://groups.google.com/group/clojure/browse_thread/thread/9dbaff59e8de9a8a/9345790eea399af9?lnk=gs
fnil, update-in, get-in
http://groups.google.com/group/clojure/browse_thread/thread/99cc4a6bfe665a6e
promise, deliver
http://groups.google.com/group/clojure/browse_frm/thread/0b1548aa40ba8072/210ec81bfe26032e?#210ec81bfe26032e
On Jun 29, 8:38 pm, Glen Stampoultzis gst...@gmail.com wrote:
On 30 June 2010 10:01, Mark Fredrickson mark.m.fredrick...@gmail.com wrote:
user (doc foo)
-
user/foo
([a b])
Adds two numbers
=== Categories ===
:bar, :baz, :other
=== See Also ===
* #'user/bar
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
=== References ===
*http://foo.com
*http://bar.com
There is also a (run-examples foo) function that evaluates the
examples.
The API/interface is in flux, but the example spells out the basics.
Call (postdoc var {:key1 value1 :key2 value2 ... }). The hash-map is
stuffed into the var's metadata, overwriting the doc-string with
additional information. Other systems could parse the map structure to
provide clickable links, etc. The system is ad-hoc --- any key is
valid and keys are used as the dispatching agent for multimethods --
so feel free to come up with additional keys. I think we should let
this grow organically for while before specifying formal semantics.
I'm gladly accepting patches, especially for postdoc.clojure.core --
the file that documents clojure.core vars (so far, only conj).
Check it out, fork it, patch it, use it, enjoy!
-Mark
I think examples on their own without a commentary to go along with
them are somewhat limited. jQuery generally has some good examples of
what detailed API documentation with examples can/should look like
-http://api.jquery.com/change/
I think extending the existing documentation with extra information is
potentially a good idea but it needs to be a commentary rather than a
plain example without extra explanation IMHO.
--
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: usage examples in clojure api docs
On 2 Lip, 09:46, Justin Kramer jkkra...@gmail.com wrote: Partly in response to this issue and partly to get my feet wet with Ring and friends, I spent the last few nights writing a proof-of- concept Wiki to collect structured Clojure usage examples: http://clojure-examples.appspot.com/ Here's a sample function page: http://clojure-examples.appspot.com/clojure.core/contains%3F I tried to come up with something that encourages a many-hands approach while maintaining structure and quality. There are plenty of missing features, but it should be easy for anyone interested to jump in and write some examples. It uses a modified version of Markdown for syntax. Content could be exported/parsed en masse relatively easily. The source is on GitHub:http://github.com/jkk/clj-wiki Does this seem like a worthwhile approach? Justin Great! I was thinking lately of building something similar with the same kind of approach. One suggestion: the core functions should be structured into categories rather than listed alphabetically., that is for example: Maps - fn1 - fn2 - fn3 Vectors - fn3 - fn4 - fn5 Arithmetic - fn6 - fn7 - fn8 etcetera. (Similar to what is in the cheat sheet) This would eliminate the tersness and it would be much easier to find a specific function (handy for newcomers to clojure) Other than that great job, I think it has big potential. It's clean, and easy to contribute. I will surely add some examples later today. -- 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: usage examples in clojure api docs
I'm very new here but I have to say I really like this. These kind of usage
examples are the most helpful resource for newcomers. I'll be happy to
contribute once I learn more.
Bob
On Jul 2, 2010, at 16:46, Justin Kramer jkkra...@gmail.com wrote:
Partly in response to this issue and partly to get my feet wet with
Ring and friends, I spent the last few nights writing a proof-of-
concept Wiki to collect structured Clojure usage examples:
http://clojure-examples.appspot.com/
Here's a sample function page:
http://clojure-examples.appspot.com/clojure.core/contains%3F
I tried to come up with something that encourages a many-hands
approach while maintaining structure and quality. There are plenty of
missing features, but it should be easy for anyone interested to jump
in and write some examples. It uses a modified version of Markdown for
syntax. Content could be exported/parsed en masse relatively easily.
The source is on GitHub: http://github.com/jkk/clj-wiki
Does this seem like a worthwhile approach?
Justin
On Jun 29, 9:35 pm, Mike Meyer mwm-keyword-googlegroups.
620...@mired.org wrote:
On Tue, 29 Jun 2010 17:01:10 -0700 (PDT)
Mark Fredrickson mark.m.fredrick...@gmail.com wrote:
On Jun 29, 5:43 pm, nickikt nick...@gmail.com wrote:
We could make it possible to add some metadata to a function
like :example or something. Then add a function called (example
function name) to print the example.
Everybody could send patches. It would be a good way to learn and a
good extra doku.
I was considering doing this for a while. This thread prompted me to
put it into action:
http://github.com/markmfredrickson/postdoc
Here is an example of it in action:
(defn foo
Adds two numbers
[a b]
(+ a b))
(defn bar
Subtracts two numbers
[a b]
(- a b))
(postdoc #'foo
{:references [http://foo.com; http://bar.com;]
:examples ['(foo 1 2) '(foo 3 4)]
:see-also [#'bar]
:categories [:bar :baz :other]})
user (doc foo)
-
user/foo
([a b])
Adds two numbers
=== Categories ===
:bar, :baz, :other
=== See Also ===
* #'user/bar
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
=== References ===
*http://foo.com
*http://bar.com
There is also a (run-examples foo) function that evaluates the
examples.
It's a great start. However, examples are much more useful if you know
what they should produce. run-examples might provide that, but having
them in the metadata would be even better - along with an explanation.
Doing that would allow the examples to be used as a set of unit tests
as well. Nuts, the things you want to test - corner cases and edge
conditions - are among the more useful things to document about a
function.
mike
--
Mike Meyer m...@mired.org http://www.mired.org/consulting.html
Independent Network/Unix/Perforce consultant, email for more information.
O ascii ribbon campaign - stop html mail -www.asciiribbon.org
--
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
--
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: usage examples in clojure api docs
+1
I like it, Justin. I was looking at making something myself but your
efforts are farther along. I'd be happy to help with any aspect of
this.
Ryan
On Fri, Jul 2, 2010 at 2:46 AM, Justin Kramer jkkra...@gmail.com wrote:
Partly in response to this issue and partly to get my feet wet with
Ring and friends, I spent the last few nights writing a proof-of-
concept Wiki to collect structured Clojure usage examples:
http://clojure-examples.appspot.com/
Here's a sample function page:
http://clojure-examples.appspot.com/clojure.core/contains%3F
I tried to come up with something that encourages a many-hands
approach while maintaining structure and quality. There are plenty of
missing features, but it should be easy for anyone interested to jump
in and write some examples. It uses a modified version of Markdown for
syntax. Content could be exported/parsed en masse relatively easily.
The source is on GitHub: http://github.com/jkk/clj-wiki
Does this seem like a worthwhile approach?
Justin
On Jun 29, 9:35 pm, Mike Meyer mwm-keyword-googlegroups.
620...@mired.org wrote:
On Tue, 29 Jun 2010 17:01:10 -0700 (PDT)
Mark Fredrickson mark.m.fredrick...@gmail.com wrote:
On Jun 29, 5:43 pm, nickikt nick...@gmail.com wrote:
We could make it possible to add some metadata to a function
like :example or something. Then add a function called (example
function name) to print the example.
Everybody could send patches. It would be a good way to learn and a
good extra doku.
I was considering doing this for a while. This thread prompted me to
put it into action:
http://github.com/markmfredrickson/postdoc
Here is an example of it in action:
(defn foo
Adds two numbers
[a b]
(+ a b))
(defn bar
Subtracts two numbers
[a b]
(- a b))
(postdoc #'foo
{:references [http://foo.com; http://bar.com;]
:examples ['(foo 1 2) '(foo 3 4)]
:see-also [#'bar]
:categories [:bar :baz :other]})
user (doc foo)
-
user/foo
([a b])
Adds two numbers
=== Categories ===
:bar, :baz, :other
=== See Also ===
* #'user/bar
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
=== References ===
*http://foo.com
*http://bar.com
There is also a (run-examples foo) function that evaluates the
examples.
It's a great start. However, examples are much more useful if you know
what they should produce. run-examples might provide that, but having
them in the metadata would be even better - along with an explanation.
Doing that would allow the examples to be used as a set of unit tests
as well. Nuts, the things you want to test - corner cases and edge
conditions - are among the more useful things to document about a
function.
mike
--
Mike Meyer m...@mired.org http://www.mired.org/consulting.html
Independent Network/Unix/Perforce consultant, email for more information.
O ascii ribbon campaign - stop html mail -www.asciiribbon.org
--
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
--
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: usage examples in clojure api docs
Hey Justin!
Nice one! I'm actually planning on doing a similar thing, but hosting it on
Amazon's EC2.
Would you be interested in combining efforts together?
Cheers,
Greg Slepak
On Jul 2, 2010, at 3:46 AM, Justin Kramer wrote:
Partly in response to this issue and partly to get my feet wet with
Ring and friends, I spent the last few nights writing a proof-of-
concept Wiki to collect structured Clojure usage examples:
http://clojure-examples.appspot.com/
Here's a sample function page:
http://clojure-examples.appspot.com/clojure.core/contains%3F
I tried to come up with something that encourages a many-hands
approach while maintaining structure and quality. There are plenty of
missing features, but it should be easy for anyone interested to jump
in and write some examples. It uses a modified version of Markdown for
syntax. Content could be exported/parsed en masse relatively easily.
The source is on GitHub: http://github.com/jkk/clj-wiki
Does this seem like a worthwhile approach?
Justin
On Jun 29, 9:35 pm, Mike Meyer mwm-keyword-googlegroups.
620...@mired.org wrote:
On Tue, 29 Jun 2010 17:01:10 -0700 (PDT)
Mark Fredrickson mark.m.fredrick...@gmail.com wrote:
On Jun 29, 5:43 pm, nickikt nick...@gmail.com wrote:
We could make it possible to add some metadata to a function
like :example or something. Then add a function called (example
function name) to print the example.
Everybody could send patches. It would be a good way to learn and a
good extra doku.
I was considering doing this for a while. This thread prompted me to
put it into action:
http://github.com/markmfredrickson/postdoc
Here is an example of it in action:
(defn foo
Adds two numbers
[a b]
(+ a b))
(defn bar
Subtracts two numbers
[a b]
(- a b))
(postdoc #'foo
{:references [http://foo.com; http://bar.com;]
:examples ['(foo 1 2) '(foo 3 4)]
:see-also [#'bar]
:categories [:bar :baz :other]})
user (doc foo)
-
user/foo
([a b])
Adds two numbers
=== Categories ===
:bar, :baz, :other
=== See Also ===
* #'user/bar
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
=== References ===
*http://foo.com
*http://bar.com
There is also a (run-examples foo) function that evaluates the
examples.
It's a great start. However, examples are much more useful if you know
what they should produce. run-examples might provide that, but having
them in the metadata would be even better - along with an explanation.
Doing that would allow the examples to be used as a set of unit tests
as well. Nuts, the things you want to test - corner cases and edge
conditions - are among the more useful things to document about a
function.
mike
--
Mike Meyer m...@mired.org http://www.mired.org/consulting.html
Independent Network/Unix/Perforce consultant, email for more information.
O ascii ribbon campaign - stop html mail -www.asciiribbon.org
--
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
--
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: usage examples in clojure api docs
Good suggestion about the categories. Making it browsable is important. A page that uses categories from the cheatsheet is easy to make. Adding categories/tags and auto-generating such a page is also doable. Code contributions are welcome. I'm not attached to App Engine; I just used it to learn about the platform. The code could be modified to work with any storage backend. I'll be spending free time in the next few days writing real examples and seeing if anyone else follows suit. If it doesn't gain traction, or someone else has a better approach, adding fancy features and re- architecting is moot. Justin On Jul 2, 5:09 am, kredaxx kred...@gmail.com wrote: On 2 Lip, 09:46, Justin Kramer jkkra...@gmail.com wrote: Partly in response to this issue and partly to get my feet wet with Ring and friends, I spent the last few nights writing a proof-of- concept Wiki to collect structured Clojure usage examples: http://clojure-examples.appspot.com/ Here's a sample function page: http://clojure-examples.appspot.com/clojure.core/contains%3F I tried to come up with something that encourages a many-hands approach while maintaining structure and quality. There are plenty of missing features, but it should be easy for anyone interested to jump in and write some examples. It uses a modified version of Markdown for syntax. Content could be exported/parsed en masse relatively easily. The source is on GitHub:http://github.com/jkk/clj-wiki Does this seem like a worthwhile approach? Justin Great! I was thinking lately of building something similar with the same kind of approach. One suggestion: the core functions should be structured into categories rather than listed alphabetically., that is for example: Maps - fn1 - fn2 - fn3 Vectors - fn3 - fn4 - fn5 Arithmetic - fn6 - fn7 - fn8 etcetera. (Similar to what is in the cheat sheet) This would eliminate the tersness and it would be much easier to find a specific function (handy for newcomers to clojure) Other than that great job, I think it has big potential. It's clean, and easy to contribute. I will surely add some examples later today. -- 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: usage examples in clojure api docs
On Fri, Jul 2, 2010 at 3:46 AM, Justin Kramer jkkra...@gmail.com wrote: Partly in response to this issue and partly to get my feet wet with Ring and friends, I spent the last few nights writing a proof-of- concept Wiki to collect structured Clojure usage examples: http://clojure-examples.appspot.com/ Here's a sample function page: http://clojure-examples.appspot.com/clojure.core/contains%3F I tried to come up with something that encourages a many-hands approach while maintaining structure and quality. There are plenty of missing features, but it should be easy for anyone interested to jump in and write some examples. It uses a modified version of Markdown for syntax. Content could be exported/parsed en masse relatively easily. The source is on GitHub: http://github.com/jkk/clj-wiki Does this seem like a worthwhile approach? Justin Nice job for getting the ball rolling on this! David -- 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: usage examples in clojure api docs
On 3 July 2010 10:12, David Nolen dnolen.li...@gmail.com wrote: On Fri, Jul 2, 2010 at 3:46 AM, Justin Kramer jkkra...@gmail.com wrote: Partly in response to this issue and partly to get my feet wet with Ring and friends, I spent the last few nights writing a proof-of- concept Wiki to collect structured Clojure usage examples: http://clojure-examples.appspot.com/ Here's a sample function page: http://clojure-examples.appspot.com/clojure.core/contains%3F I tried to come up with something that encourages a many-hands approach while maintaining structure and quality. There are plenty of missing features, but it should be easy for anyone interested to jump in and write some examples. It uses a modified version of Markdown for syntax. Content could be exported/parsed en masse relatively easily. The source is on GitHub: http://github.com/jkk/clj-wiki Does this seem like a worthwhile approach? Justin Nice job for getting the ball rolling on this! David +1 Perfect! I'd encourage everyone to get behind this. The barrier to entry is very low so no reason not to help out. The only thing missing is a search system. Also it would probably be a good idea to make the licensing of contributions explicit (boring but important detail). I didn't see anything on the site about that. -- 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: usage examples in clojure api docs
Mark Fredrickson wrote:
Hello Tim,
Knuth originally created an idea of literate programming
where you embed source code into latex documents. He called
such documents web documents (because nobody had yet used
the word web).
Thanks for passing along your code. I have some familiarity with
noweb. I use Sweave every day (R's noweb implementation), though not
for many of its more advanced features. I specifically avoided the
using the phrase literate programming for a few reasons:
1. I have never defined chunks in different orders than they should
execute. I have no need for this feature. As I understand it, out-of-
order chunks are a cornerstone of the lit. prog. model.
Actually I rarely use this feature.
I do use the fact that equal chunk names get combined so that I can split a
large chunk into parts and add explanations in the middle.
2. Insofar as literate programming implies noweb, I dislike the
=/@ syntax. Moreover, this syntax requires a smarter parser to
understand any options inside the ...= directives. My parser is
dumb. My insight is that I can do the same things as echo = TRUE=
through a macro (output-forms ...). The system is extensible, unlike
noweb.
Literate programming and noweb are independent. As I said, the lisp
version of tangle
uses latex syntax such as
\begin{chunk}{some chunk name}
(your code)
\end{chunk}
rather than the
some chunk name=
(your code)
@
This has the considerable advantage that your document is pure latex.
3. Insofar as literate programming implies LaTeX, while I write a
lot of TeX, I intend to use this system for blog posts, README files,
perhaps even inline documentation as mentioned above. My experience
with Sweave shows that writing other document types is not the
default. Perhaps there is an option to not inject \Schunk{...} into
my .txt files, but changeling is designed from the group up to support
many different output contexts.
The same magic can happen in TeX since latex is only a macro layer.
I may be reinventing the wheel, but mine has bling rims. ;-)
The details are not important but the use of literate programming (or
whatever term
you prefer) is important and can dramatically change the quality of the
system.
-Mark
--
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: usage examples in clojure api docs
I like the idea of having example code for all the functions. However, speaking for myself only, I don't think that the doc strings are the place for a comprehensive set of examples. How about building them in some external place? (Maybe as a separate github project to begin with.) In particular, it would be nice if the examples used some literate programming technique that let users open the examples and play with them. That way, they could be linked to from the documentation (I could roll it into autodoc, for instance, subject to Rich and Stuart's constraints) but also directly opened, tried, copied, etc. from your editor and repl. It's easy for me to imagine that, in the not too distant future, we could roll that into Clojure core in a way similar to the tests. Tom On Jun 28, 9:06 pm, cageface milese...@gmail.com wrote: Several people have suggested that usage examples in the docs would be helpful and this is something I often find myself wishing for. Are patches introducing examples welcomed by the core team? -- 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: usage examples in clojure api docs
There is Walton that covers that. Talk to defn in #clojure if you want to know detail Regards, Heinz Sent from my iPad On Jun 29, 2010, at 6:06 AM, cageface milese...@gmail.com wrote: Several people have suggested that usage examples in the docs would be helpful and this is something I often find myself wishing for. Are patches introducing examples welcomed by the core team? -- 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 -- 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: usage examples in clojure api docs
Hi people! I love PHP documentation http://www.php.net/manual/en/ and its function reference: http://www.php.net/manual/en/funcref.php Each function has a dedicated page, with detailed description, initial examples. And visitors can add new examples or limit cases. Example: http://www.php.net/manual/en/function.array-combine.php And the documentation can be built in .pdf and other formats. I never need an irc channel or send an email in a list to understand a function. Maybe for other topics, but not to understand a function. That's the level of function documentation to match, I guess. And it's pretty good in the non-function part: good explanation of language and its usage. Angel Java Lopez http://www.ajlopez.com http://twitter.com/ajlopez On Tue, Jun 29, 2010 at 1:06 AM, cageface milese...@gmail.com wrote: Several people have suggested that usage examples in the docs would be helpful and this is something I often find myself wishing for. Are patches introducing examples welcomed by the core team? -- 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.comclojure%2bunsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -- 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: usage examples in clojure api docs
I've wanted to work on expanded documentation for Clojure, too, both as a way to contribute something I think is needed and as a way to learn Clojure. To illustrate what I have in mind, I put together an example of new documentation for 'conj' located here (a read-only google doc, for now): http://bit.ly/9YOvgP Try to imagine the information tastefully laid out with a lot of hyperlinking, category cross-referencing and additional organization à la the Clojure Cheat Sheet. Not only would it be a way to see example code, both toy examples and real-world examples, but also a way to tie together related functions/macros, explanations and/or outside linking for some of the larger concepts (like clojure.org sidebar topics, links to relevant videos, books?, etc.) The target audience I had in mind would be people who want to learn clojure and want to have an available reference more expository than the current API docs. Please note that I'm still learning Clojure and one or more bits of information at the above link may be incorrect! And it's still very unfinished; I know at least one of the terms used is incorrect (items? I whipped it together ...). I would welcome corrections and explanations, even if what I've produced so far is just a simple example of what could be. - Ryan Waters On Tue, Jun 29, 2010 at 9:34 AM, Angel Java Lopez ajlopez2...@gmail.com wrote: Hi people! I love PHP documentation http://www.php.net/manual/en/ and its function reference: http://www.php.net/manual/en/funcref.php Each function has a dedicated page, with detailed description, initial examples. And visitors can add new examples or limit cases. Example: http://www.php.net/manual/en/function.array-combine.php And the documentation can be built in .pdf and other formats. I never need an irc channel or send an email in a list to understand a function. Maybe for other topics, but not to understand a function. That's the level of function documentation to match, I guess. And it's pretty good in the non-function part: good explanation of language and its usage. Angel Java Lopez http://www.ajlopez.com http://twitter.com/ajlopez On Tue, Jun 29, 2010 at 1:06 AM, cageface milese...@gmail.com wrote: Several people have suggested that usage examples in the docs would be helpful and this is something I often find myself wishing for. Are patches introducing examples welcomed by the core team? -- 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 -- 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 -- 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: usage examples in clojure api docs
I don't know about the accuracy either but I think this is great in terms of coverage and organization. BTW cons is from Lisp, short for construct. -Lee On Jun 29, 2010, at 5:16 PM, Ryan Waters wrote: I've wanted to work on expanded documentation for Clojure, too, both as a way to contribute something I think is needed and as a way to learn Clojure. To illustrate what I have in mind, I put together an example of new documentation for 'conj' located here (a read-only google doc, for now): http://bit.ly/9YOvgP Try to imagine the information tastefully laid out with a lot of hyperlinking, category cross-referencing and additional organization à la the Clojure Cheat Sheet. Not only would it be a way to see example code, both toy examples and real-world examples, but also a way to tie together related functions/macros, explanations and/or outside linking for some of the larger concepts (like clojure.org sidebar topics, links to relevant videos, books?, etc.) The target audience I had in mind would be people who want to learn clojure and want to have an available reference more expository than the current API docs. Please note that I'm still learning Clojure and one or more bits of information at the above link may be incorrect! And it's still very unfinished; I know at least one of the terms used is incorrect (items? I whipped it together ...). I would welcome corrections and explanations, even if what I've produced so far is just a simple example of what could be. - Ryan Waters -- Lee Spector, Professor of Computer Science School of Cognitive Science, Hampshire College 893 West Street, Amherst, MA 01002-3359 lspec...@hampshire.edu, http://hampshire.edu/lspector/ Phone: 413-559-5352, Fax: 413-559-5438 Check out Genetic Programming and Evolvable Machines: http://www.springer.com/10710 - http://gpemjournal.blogspot.com/ -- 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: usage examples in clojure api docs
We could make it possible to add some metadata to a function like :example or something. Then add a function called (example function name) to print the example. Everybody could send patches. It would be a good way to learn and a good extra doku. On Jun 30, 12:29 am, Lee Spector lspec...@hampshire.edu wrote: I don't know about the accuracy either but I think this is great in terms of coverage and organization. BTW cons is from Lisp, short for construct. -Lee On Jun 29, 2010, at 5:16 PM, Ryan Waters wrote: I've wanted to work on expanded documentation for Clojure, too, both as a way to contribute something I think is needed and as a way to learn Clojure. To illustrate what I have in mind, I put together an example of new documentation for 'conj' located here (a read-only google doc, for now): http://bit.ly/9YOvgP Try to imagine the information tastefully laid out with a lot of hyperlinking, category cross-referencing and additional organization à la the Clojure Cheat Sheet. Not only would it be a way to see example code, both toy examples and real-world examples, but also a way to tie together related functions/macros, explanations and/or outside linking for some of the larger concepts (like clojure.org sidebar topics, links to relevant videos, books?, etc.) The target audience I had in mind would be people who want to learn clojure and want to have an available reference more expository than the current API docs. Please note that I'm still learning Clojure and one or more bits of information at the above link may be incorrect! And it's still very unfinished; I know at least one of the terms used is incorrect (items? I whipped it together ...). I would welcome corrections and explanations, even if what I've produced so far is just a simple example of what could be. - Ryan Waters -- Lee Spector, Professor of Computer Science School of Cognitive Science, Hampshire College 893 West Street, Amherst, MA 01002-3359 lspec...@hampshire.edu,http://hampshire.edu/lspector/ Phone: 413-559-5352, Fax: 413-559-5438 Check out Genetic Programming and Evolvable Machines:http://www.springer.com/10710-http://gpemjournal.blogspot.com/ -- 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: usage examples in clojure api docs
On 29 June 2010 09:13, Tom Faulhaber tomfaulha...@gmail.com wrote: However, speaking for myself only, I don't think that the doc strings are the place for a comprehensive set of examples. Seconded. On 29 June 2010 12:33, Heinz N. Gies he...@licenser.net wrote: There is Walton that covers that. Talk to defn in #clojure if you want to know detail Or have a look at the GitHub repo: http://github.com/defn/walton Here's a link to one the page on clojure.core/reverse: http://getclojure.org:8080/examples/reverse Sincerely, Michał -- 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: usage examples in clojure api docs
On Jun 29, 5:43 pm, nickikt nick...@gmail.com wrote:
We could make it possible to add some metadata to a function
like :example or something. Then add a function called (example
function name) to print the example.
Everybody could send patches. It would be a good way to learn and a
good extra doku.
I was considering doing this for a while. This thread prompted me to
put it into action:
http://github.com/markmfredrickson/postdoc
Here is an example of it in action:
(defn foo
Adds two numbers
[a b]
(+ a b))
(defn bar
Subtracts two numbers
[a b]
(- a b))
(postdoc #'foo
{:references [http://foo.com; http://bar.com;]
:examples ['(foo 1 2) '(foo 3 4)]
:see-also [#'bar]
:categories [:bar :baz :other]})
user (doc foo)
-
user/foo
([a b])
Adds two numbers
=== Categories ===
:bar, :baz, :other
=== See Also ===
* #'user/bar
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
=== References ===
* http://foo.com
* http://bar.com
There is also a (run-examples foo) function that evaluates the
examples.
The API/interface is in flux, but the example spells out the basics.
Call (postdoc var {:key1 value1 :key2 value2 ... }). The hash-map is
stuffed into the var's metadata, overwriting the doc-string with
additional information. Other systems could parse the map structure to
provide clickable links, etc. The system is ad-hoc --- any key is
valid and keys are used as the dispatching agent for multimethods --
so feel free to come up with additional keys. I think we should let
this grow organically for while before specifying formal semantics.
I'm gladly accepting patches, especially for postdoc.clojure.core --
the file that documents clojure.core vars (so far, only conj).
Check it out, fork it, patch it, use it, enjoy!
-Mark
--
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: usage examples in clojure api docs
On 30 June 2010 10:01, Mark Fredrickson mark.m.fredrick...@gmail.com wrote:
user (doc foo)
-
user/foo
([a b])
Adds two numbers
=== Categories ===
:bar, :baz, :other
=== See Also ===
* #'user/bar
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
=== References ===
* http://foo.com
* http://bar.com
There is also a (run-examples foo) function that evaluates the
examples.
The API/interface is in flux, but the example spells out the basics.
Call (postdoc var {:key1 value1 :key2 value2 ... }). The hash-map is
stuffed into the var's metadata, overwriting the doc-string with
additional information. Other systems could parse the map structure to
provide clickable links, etc. The system is ad-hoc --- any key is
valid and keys are used as the dispatching agent for multimethods --
so feel free to come up with additional keys. I think we should let
this grow organically for while before specifying formal semantics.
I'm gladly accepting patches, especially for postdoc.clojure.core --
the file that documents clojure.core vars (so far, only conj).
Check it out, fork it, patch it, use it, enjoy!
-Mark
I think examples on their own without a commentary to go along with
them are somewhat limited. jQuery generally has some good examples of
what detailed API documentation with examples can/should look like -
http://api.jquery.com/change/
I think extending the existing documentation with extra information is
potentially a good idea but it needs to be a commentary rather than a
plain example without extra explanation IMHO.
--
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: usage examples in clojure api docs
On Tue, 29 Jun 2010 17:01:10 -0700 (PDT)
Mark Fredrickson mark.m.fredrick...@gmail.com wrote:
On Jun 29, 5:43 pm, nickikt nick...@gmail.com wrote:
We could make it possible to add some metadata to a function
like :example or something. Then add a function called (example
function name) to print the example.
Everybody could send patches. It would be a good way to learn and a
good extra doku.
I was considering doing this for a while. This thread prompted me to
put it into action:
http://github.com/markmfredrickson/postdoc
Here is an example of it in action:
(defn foo
Adds two numbers
[a b]
(+ a b))
(defn bar
Subtracts two numbers
[a b]
(- a b))
(postdoc #'foo
{:references [http://foo.com; http://bar.com;]
:examples ['(foo 1 2) '(foo 3 4)]
:see-also [#'bar]
:categories [:bar :baz :other]})
user (doc foo)
-
user/foo
([a b])
Adds two numbers
=== Categories ===
:bar, :baz, :other
=== See Also ===
* #'user/bar
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
=== References ===
* http://foo.com
* http://bar.com
There is also a (run-examples foo) function that evaluates the
examples.
It's a great start. However, examples are much more useful if you know
what they should produce. run-examples might provide that, but having
them in the metadata would be even better - along with an explanation.
Doing that would allow the examples to be used as a set of unit tests
as well. Nuts, the things you want to test - corner cases and edge
conditions - are among the more useful things to document about a
function.
mike
--
Mike Meyer m...@mired.org http://www.mired.org/consulting.html
Independent Network/Unix/Perforce consultant, email for more information.
O ascii ribbon campaign - stop html mail - www.asciiribbon.org
--
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: usage examples in clojure api docs
It's a great start. However, examples are much more useful if you know what they should produce. run-examples might provide that, but having them in the metadata would be even better - along with an explanation. From my original email: === Examples === (foo 1 2) 3 (foo 3 4) 7 But still not exactly what you are looking for. Perhaps you would prefer another of my fledgling projects: http://github.com/markmfredrickson/changeling My use case is writing LaTeX documents that include analysis and graphs produced in Clojure (more specifically Incanter), like Sweave for R, but you could use it to create function documentation as well. To summarize the differences of the two packages: with Changeling you are writing text files with embedded Clojure code; with postdoc you are writing Clojure with embedded text and code. Feel free to use these now. Changeling will go on Clojars after I get a LaTeX context written and generic image output. postdoc is still too new for me to say when it will see its first release. -Mark -- 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: usage examples in clojure api docs
Mark,
Knuth originally created an idea of literate programming
where you embed source code into latex documents. He called
such documents web documents (because nobody had yet used
the word web).
tangle doc.web == executable source code
weave doc.web == latex document
Knuth's web assumes you are writing in the hot new language
that was sweeping the world called Pascal.
There is a package called noweb by Norman Ramsey that uses
markup that is independent of the language. You write your
text and code-chunks. A chunk is delimited by
name of the chunk=
(your spiffy source code)
@
noweb will extract the chunks using
notangle doc.web == executable source code
noweave doc.web == latex document
As a further refinement I wrote some simple latex macros
that use latex commands to delimit chunks. This has the
feature that your document is pure latex and you don't
need the weave function at all. All you need is the
tangle function.
Now if your lisp just happens to have a tangle function
implemented then your lisp can read latex documents and
extract the source code directly.
I've attached an implementation of a lisp version of
tangle (common lisp but it would be a student exercise
to rewrite it in clojure since it does nothing clever).
So in the end you get to write latex documents that include
inline clojure lisp code and you can read your source code
directly out of your documents. That way you can publish your
book and be certain that your examples actually compile and
run correctly.
For an example of excellent literate programming documentation
see Lisp In Small Pieces by Christian Queinnac. He implements
a full lisp including the compiler, interpreter, etc and
explains everything in english.
If clojure were documented this way we could all just sit
and read the details like a novel.
Tim
Mark Fredrickson wrote:
It's a great start. However, examples are much more useful if you know
what they should produce. run-examples might provide that, but having
them in the metadata would be even better - along with an explanation.
From my original email:
=== Examples ===
(foo 1 2)
3
(foo 3 4)
7
But still not exactly what you are looking for. Perhaps you would
prefer another of my fledgling projects:
http://github.com/markmfredrickson/changeling
My use case is writing LaTeX documents that include analysis and
graphs produced in Clojure (more specifically Incanter), like Sweave
for R, but you could use it to create function documentation as well.
To summarize the differences of the two packages: with Changeling you
are writing text files with embedded Clojure code; with postdoc you
are writing Clojure with embedded text and code.
Feel free to use these now. Changeling will go on Clojars after I get
a LaTeX context written and generic image output. postdoc is still too
new for me to say when it will see its first release.
-Mark
; 0 AUTHOR and LICENSE
; 1 ABSTRACT
; 2 THE LATEX SUPPORT CODE
; 3 GLOBALS
; 4 THE TANGLE COMMAND
; 5 THE TANGLE FUNCTION
; 6 GCL-READ-FILE (aka read-sequence)
; 7 GCL-HASHCHUNKS
; 8 GCL-EXPAND
; 9 ISCHUNK-LATEX
; 10 ISCHUNK-NOWEB
;;; 0 AUTHOR and LICENSE
;;; Timothy Daly (d...@axiom-developer.org)
;;; License: Public Domain
;;; 1 ABSTRACT
;;; This program will extract the source code from a literate file
;;; A literate lisp file contains a mixture of latex and lisp sources code.
;;; The file is intended to be in one of two formats, either in latex
;;; format or, for legacy reasons, in noweb format.
;;; Latex format files defines a newenvironment so that code chunks
;;; can be delimited by \begin{chunk}{name} \end{chunk} blocks
;;; This is supported by the following latex code.
;;; 2 THE LATEX SUPPORT CODE
;;; The verbatim package quotes everything within its grasp and is used to
;;; hide and quote the source code during latex formatting. The verbatim
;;; environment is built in but the package form lets us use it in our
;;; chunk environment and it lets us change the font.
;;;
;;; \usepackage{verbatim}
;;;
;;; Make the verbatim font smaller
;;; Note that we have to temporarily change the '@' to be just a character
;;; because the \verba...@font name uses it as a character
;;;
;;; \chardef\atcode=\catcode`\@
;;; \catcod...@=11
;;; \renewcommand{\verba...@font}{\ttfamily\small}
;;; \catcod...@=\atcode
;;; This declares a new environment named ``chunk'' which has one
;;; argument that is the name of the chunk. All code needs to live
;;; between the \begin{chunk}{name} and the \end{chunk}
;;; The ``name'' is used to define the chunk.
;;; Reuse of the same chunk name later concatenates the chunks
;;; For those of you who can't read latex this says:
;;; Make a new environment named chunk with one argument
;;; The first
usage examples in clojure api docs
Several people have suggested that usage examples in the docs would be helpful and this is something I often find myself wishing for. Are patches introducing examples welcomed by the core team? -- 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
