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?
> 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)?
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 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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
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
On Wed, Jul 25, 2012 at 12:17 PM, Laurent PETIT <laurent.pe...@gmail.com>wrote:
> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@gmail.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)?
> 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 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+unsubscribe@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
Laurent PETIT <laurent.pe...@gmail.com> 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---
> 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"
2012/7/25 Dimitrios Jim Piliouras <jimpil1...@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)
> On Wed, Jul 25, 2012 at 12:17 PM, Laurent PETIT <laurent.pe...@gmail.com>wrote:
>> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@gmail.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)?
>> 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 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+unsubscribe@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+unsubscribe@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
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
On Wed, Jul 25, 2012 at 4:02 PM, Laurent PETIT <laurent.pe...@gmail.com>wrote:
> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@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)
>> Jim
>> On Wed, Jul 25, 2012 at 12:17 PM, Laurent PETIT <laurent.pe...@gmail.com>wrote:
>>> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@gmail.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)?
>>> 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 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+unsubscribe@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+unsubscribe@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+unsubscribe@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
2012/7/25 Dimitrios Jim Piliouras <jimpil1...@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...
> 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
> On Wed, Jul 25, 2012 at 4:02 PM, Laurent PETIT <laurent.pe...@gmail.com>wrote:
>> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@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)
>>> Jim
>>> On Wed, Jul 25, 2012 at 12:17 PM, Laurent PETIT <laurent.pe...@gmail.com
>>> > wrote:
>>>> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@gmail.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)?
>>>> 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 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+unsubscribe@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+unsubscribe@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+unsubscribe@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+unsubscribe@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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
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.
> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@gmail.com<javascript:_e({}, 'cvml', 'jimpil1...@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
> 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
> On Wed, Jul 25, 2012 at 4:02 PM, Laurent PETIT <laurent.pe...@gmail.com>wrote:
> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@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)
> Jim
> On Wed, Jul 25, 2012 at 12:17 PM, Laurent PETIT <laurent.pe...@gmail.com>wrote:
> 2012/7/25 Dimitrios Jim Piliouras <jimpil1...@gmail.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)?
> 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 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
> --
> 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<javascript:_e({}, 'cvml', '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+unsubscribe@googlegroups.com <javascript:_e({}, 'cvml',
> 'clojure%2Bunsubscribe@googlegroups.com');>
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
> 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:
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.
On Jul 25, 2012, at 7:25 PM, Mark Derricutt wrote:
> 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:
> The IDE gives a nice code browser, navigating between namespaces and functions in a collapsible manner along with a REPL.
> 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+unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
> 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.
> 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.
On Wednesday, July 25, 2012 8:16:52 AM UTC-4, Tassilo Horn wrote:
> 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.
