seesaw's beautiful docstrings
398 views
Skip to first unread message
Dimitrios Jim Piliouras
Jul 25, 2012, 4:50:55 AM7/25/12
to clo...@googlegroups.com
Hi all,
I've just watched Dave Ray's mini demo of seesaw on infoQ and what amazed me (apart from the actual library) was the gorgeous documentation that is attached to all the functions. Dave has done an amazing job - even though it is essentially a swing wrapper you can get a lot done without knowing any swing at all!!! This is pretty good stuff...I was wondering if there is an easier way to generate docstrings like that without alligning spaces and tab manuallys and more importantly without inlining them with the functions. I know it sounds a bit silly but if your source code is dominated by docs then it is really hard to navigate up and down...I am generally trying to keep my docs minimal with only plain english and rarely more than 3-4 lines. However, after seeing what Dave has done I feel rather jealous! Whenever I tried to produce docs like his the result is rather ugly unless i systematically fiddle with it through trial and error...So in essence 2 questions:
-Is there a way write the docs in a separate place (different section of the document or different document altogether)?
-Is there another way to style your documentation text other than manual evolutionary means (trial and error)?
Just in case Dave is lurking around,
-You actually wrote and styled all that documentation by hand?
Jim
I've just watched Dave Ray's mini demo of seesaw on infoQ and what amazed me (apart from the actual library) was the gorgeous documentation that is attached to all the functions. Dave has done an amazing job - even though it is essentially a swing wrapper you can get a lot done without knowing any swing at all!!! This is pretty good stuff...I was wondering if there is an easier way to generate docstrings like that without alligning spaces and tab manuallys and more importantly without inlining them with the functions. I know it sounds a bit silly but if your source code is dominated by docs then it is really hard to navigate up and down...I am generally trying to keep my docs minimal with only plain english and rarely more than 3-4 lines. However, after seeing what Dave has done I feel rather jealous! Whenever I tried to produce docs like his the result is rather ugly unless i systematically fiddle with it through trial and error...So in essence 2 questions:
-Is there a way write the docs in a separate place (different section of the document or different document altogether)?
-Is there another way to style your documentation text other than manual evolutionary means (trial and error)?
Just in case Dave is lurking around,
-You actually wrote and styled all that documentation by hand?
Jim
Laurent PETIT
Jul 25, 2012, 5:17:34 AM7/25/12
to clo...@googlegroups.com
2012/7/25 Dimitrios Jim Piliouras <jimpi...@gmail.com>
Third option : use an editor/IDE which allows you to "fold" docs (one by one / fold all / unfold all), and / or to navigate in your source code via "code outlines"
Just in case Dave is lurking around,
-You actually wrote and styled all that documentation by hand?
Jim
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@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+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
Dimitrios Jim Piliouras
Jul 25, 2012, 5:32:52 AM7/25/12
to clo...@googlegroups.com
Hmmm I see...you're saying that this is all due to my minimalistic repl enviroment (raw terminal embedded in gedit + leiningen2)...I know eclipse does folding and stuff but what about when you want to hit <enter> to break a line and then you want to align some other sentence underneath? will it show on the raw terminal exactly as it shows on the eclipse text-editor? I'm asking because in gedit the only way i can predict where things go is whenever i have a continuous string (no line breaks)...
Jim
Jim
Meikel Brandmeyer (kotarak)
Jul 25, 2012, 5:56:45 AM7/25/12
to clo...@googlegroups.com
Hi,
you should choose a fixed width font. Then you can line up sentences without problems using spaces. Inconvenient, but doable.
Kind regards
Meikel
you should choose a fixed width font. Then you can line up sentences without problems using spaces. Inconvenient, but doable.
Kind regards
Meikel
Tassilo Horn
Jul 25, 2012, 8:16:52 AM7/25/12
to clo...@googlegroups.com
Laurent PETIT <lauren...@gmail.com> writes:
>> -Is there a way write the docs in a separate place (different section
>> of the document or different document altogether)?
Sure.
>> -Is there a way write the docs in a separate place (different section
>> of the document or different document altogether)?
--8<---------------cut here---------------start------------->8---
(defn plus1 [x] (+ x 1))
(alter-meta! #'plus1 assoc :doc "Adds one to x.")
--8<---------------cut here---------------end--------------->8---
> Third option : use an editor/IDE which allows you to "fold" docs (one
> by one / fold all / unfold all), and / or to navigate in your source
> code via "code outlines"
Bye,
Tassilo
Laurent PETIT
Jul 25, 2012, 9:02:47 AM7/25/12
to clo...@googlegroups.com
2012/7/25 Dimitrios Jim Piliouras <jimpi...@gmail.com>
Hmmm I see...you're saying that this is all due to my minimalistic repl enviroment (raw terminal embedded in gedit + leiningen2)...I know eclipse does folding and stuff but what about when you want to hit <enter> to break a line and then you want to align some other sentence underneath? will it show on the raw terminal exactly as it shows on the eclipse text-editor? I'm asking because in gedit the only way i can predict where things go is whenever i have a continuous string (no line breaks)...
tbh, Counterclockwise does not yet have folding (tho it is a WIP in a contributor's branch I haven't yet had the time to review - shame on me)
Dimitrios Jim Piliouras
Jul 25, 2012, 5:13:44 PM7/25/12
to clo...@googlegroups.com
ooo thanks Tassilo...I knew that the docstring is stored as metadata but I did not know I could mutate it after the binding is set..this is very cool on its own!
As far as IDEs go i will have a look around even though i was quite happy with my minimal setup...I also tend to use clooj when on the road which is steadily getting better...I gave ccw several chances as I was totally in love with eclipse in my java days, but even though I do like the editor and all the clever things it can do, I still cannot get my head round how to work efficiently on the eclipse repl...I specifically remember spawning a new repl every time i was loading a namespace which seemed very odd cos i had to close them all at the end... emacs on the other hand seems more like a religion rather than an editor!!! The thing is my timetable atm does not allow any deviations and it would big deviation if i was to decide to learn emacs any time soon....
thank you both for your precious time and suggestions... cheers!
Jim
As far as IDEs go i will have a look around even though i was quite happy with my minimal setup...I also tend to use clooj when on the road which is steadily getting better...I gave ccw several chances as I was totally in love with eclipse in my java days, but even though I do like the editor and all the clever things it can do, I still cannot get my head round how to work efficiently on the eclipse repl...I specifically remember spawning a new repl every time i was loading a namespace which seemed very odd cos i had to close them all at the end... emacs on the other hand seems more like a religion rather than an editor!!! The thing is my timetable atm does not allow any deviations and it would big deviation if i was to decide to learn emacs any time soon....
thank you both for your precious time and suggestions... cheers!
Jim
Laurent PETIT
Jul 25, 2012, 6:26:05 PM7/25/12
to clo...@googlegroups.com
2012/7/25 Dimitrios Jim Piliouras <jimpi...@gmail.com>
ooo thanks Tassilo...I knew that the docstring is stored as metadata but I did not know I could mutate it after the binding is set..this is very cool on its own!
As far as IDEs go i will have a look around even though i was quite happy with my minimal setup...I also tend to use clooj when on the road which is steadily getting better...I gave ccw several chances as I was totally in love with eclipse in my java days, but even though I do like the editor and all the clever things it can do, I still cannot get my head round how to work efficiently on the eclipse repl...I specifically remember spawning a new repl every time i was loading a namespace which seemed very odd cos i had to close them all at the end...
Then by all means give ccw another try
Dave Ray
Jul 25, 2012, 9:06:02 PM7/25/12
to clo...@googlegroups.com
For what it's worth, the docstrings are indeed hand-formatted, but that's pretty easy with vim or any decent editor. The size of the docstrings is a bit of a problem. At one point on Twitter Fogus suggested that Trammel could help off-load documentation elsewhere, but I never was motivated enough to pursue it.
Cheers,
Dave
Mark Derricutt
Jul 25, 2012, 10:25:56 PM7/25/12
to clo...@googlegroups.com
On 25/07/12 9:17 PM, Laurent PETIT wrote:
> Third option : use an editor/IDE which allows you to "fold" docs (one
> by one / fold all / unfold all), and / or to navigate in your source
> code via "code outlines"
I was just musing on wanting a Hopscotch style IDE for clojure:
> Third option : use an editor/IDE which allows you to "fold" docs (one
> by one / fold all / unfold all), and / or to navigate in your source
> code via "code outlines"
http://theoryinpractise.tumblr.com/post/28023552869/everytime-i-tinker-with-newspeak-i-keep-thinking
The IDE gives a nice code browser, navigating between namespaces and
functions in a collapsible manner along with a REPL.
Mark
Frank Siebenlist
Jul 25, 2012, 11:40:40 PM7/25/12
to clo...@googlegroups.com, Frank Siebenlist
We have an smalltalk-like clojure namespace/var/type-browser for docstrings/clojuredocs/source at "https://github.com/franks42/clj-ns-browser" that may be of use… which happens to be built on top of seesaw.
-FrankS.
-FrankS.
Mark Derricutt
Jul 26, 2012, 12:44:20 AM7/26/12
to clo...@googlegroups.com
On 26/07/12 3:40 PM, Frank Siebenlist wrote:
> We have an smalltalk-like clojure namespace/var/type-browser for docstrings/clojuredocs/source at "https://github.com/franks42/clj-ns-browser" that may be of use� which happens to be built on top of seesaw.
>
Hey that looks awesome! I saw it mentioned awhile back but it's come a
long way since I last peeked.
Mark
> We have an smalltalk-like clojure namespace/var/type-browser for docstrings/clojuredocs/source at "https://github.com/franks42/clj-ns-browser" that may be of use� which happens to be built on top of seesaw.
>
Hey that looks awesome! I saw it mentioned awhile back but it's come a
long way since I last peeked.
Mark
Tassilo Horn
Jul 26, 2012, 5:10:43 AM7/26/12
to clo...@googlegroups.com
Laurent PETIT <lauren...@gmail.com> writes:
Hi!
> Third option : use an editor/IDE which allows you to "fold" docs (one
> by one / fold all / unfold all), and / or to navigate in your source
> code via "code outlines"
BTW, I just noticed that you can use Emacs' hs-minor-mode to fold
top-level forms. For example, when you fold
(defmacro when-not
"Evaluates test. If logical false, evaluates body in an implicit do."
{:added "1.0"}
[test & body]
(list 'if test nil (cons 'do body)))
what's displayed is just
(defmacro when-not...)
That's pretty nice, but its not very clojure specific. For example, if
metadata precedes the var name, it doesn't work.
(def
^{:arglists '([coll])
:doc "Return the last item in coll, in linear time"
:added "1.0"
:static true}
last (fn ^:static last [s]
(if (next s)
(recur (next s))
(first s))))
becomes just
(def ...)
But hideshow.el has some customization possibilities, so probably it
could be tuned to do more clojure-specific folding.
Bye,
Tassilo
Hi!
> Third option : use an editor/IDE which allows you to "fold" docs (one
> by one / fold all / unfold all), and / or to navigate in your source
> code via "code outlines"
top-level forms. For example, when you fold
(defmacro when-not
"Evaluates test. If logical false, evaluates body in an implicit do."
{:added "1.0"}
[test & body]
(list 'if test nil (cons 'do body)))
what's displayed is just
(defmacro when-not...)
That's pretty nice, but its not very clojure specific. For example, if
metadata precedes the var name, it doesn't work.
(def
^{:arglists '([coll])
:doc "Return the last item in coll, in linear time"
:added "1.0"
:static true}
last (fn ^:static last [s]
(if (next s)
(recur (next s))
(first s))))
becomes just
(def ...)
But hideshow.el has some customization possibilities, so probably it
could be tuned to do more clojure-specific folding.
Bye,
Tassilo
John Gabriele
Jul 27, 2012, 12:43:18 PM7/27/12
to clo...@googlegroups.com
On Wednesday, July 25, 2012 8:16:52 AM UTC-4, Tassilo Horn wrote:
Wow, that's nice...
Reminds me of the paths that Python and Perl have taken regarding this issue.
Python goes with having very short docstrings, but then longer separate documentation available elsewhere. I'm personally not crazy about this approach, because I usually end up wanting to know more than the rather skimpy docstrings tell me.
Perl 5 doesn't have docstrings, but they do have an embedded "POD" markup doc format, the content of which often serves as docstrings (though POD is also used for longer external docs as well). I'm much happier with the richer Perl 5 docs, but the issue of having all those docs clog up your code had led to a best practice of just moving them all to the end of the file.
Tassilo's note that you can use `alter-meta!` for roughly the same thing seems similar to the Perl 5 approach giving you the best of both worlds:
* you end up with more complete docstrings (making your users happier),
* that don't clog up your code (or require code-folding to achieve that end), and
* that still go in the same source file (thus keeping your code and api docs together).
I'd imagine that it wouldn't be too difficult to create a tool to extract docstrings out into alter-metas at the bottom, or the reverse --- gather up alter-metas at the bottom and stitch them into their respective function defns, if that's your preference.
I like it. Make your docstrings as long as they need to be (perhaps add some examples?). Even format them in markdown to make them more readable in the repl.
---John
Laurent PETIT writes:
>> -Is there a way write the docs in a separate place (different section
>> of the document or different document altogether)?
Sure.
--8<---------------cut here---------------start------------->8---
(defn plus1 [x] (+ x 1))
(alter-meta! #'plus1 assoc :doc "Adds one to x.")
--8<---------------cut here---------------end--------------->8---
Wow, that's nice...
Reminds me of the paths that Python and Perl have taken regarding this issue.
Python goes with having very short docstrings, but then longer separate documentation available elsewhere. I'm personally not crazy about this approach, because I usually end up wanting to know more than the rather skimpy docstrings tell me.
Perl 5 doesn't have docstrings, but they do have an embedded "POD" markup doc format, the content of which often serves as docstrings (though POD is also used for longer external docs as well). I'm much happier with the richer Perl 5 docs, but the issue of having all those docs clog up your code had led to a best practice of just moving them all to the end of the file.
Tassilo's note that you can use `alter-meta!` for roughly the same thing seems similar to the Perl 5 approach giving you the best of both worlds:
* you end up with more complete docstrings (making your users happier),
* that don't clog up your code (or require code-folding to achieve that end), and
* that still go in the same source file (thus keeping your code and api docs together).
I'd imagine that it wouldn't be too difficult to create a tool to extract docstrings out into alter-metas at the bottom, or the reverse --- gather up alter-metas at the bottom and stitch them into their respective function defns, if that's your preference.
I like it. Make your docstrings as long as they need to be (perhaps add some examples?). Even format them in markdown to make them more readable in the repl.
---John
Reply all
Reply to author
Forward
0 new messages