Re: Proposing a new Clojure documentation system (in Clojure)

[Edwin Watkeys]

On Tuesday, May 6, 2014 10:39:47 AM UTC-4, Gregg Reynolds wrote:
>
>
> On Tue, May 6, 2014 at 4:53 AM, Phillip Lord  > wrote:
>
Trivial things that I would like to be able to do that I cannot do (in a
>>
> way which will be reliably interpreted).
>>
>>  - Add hyperlinks
>>  - Distinguish between symbols (or names of vars) and normal words.
>>  - Distinguish between code (examples) and normal words
>>  - Have access to basic "markdown" style typography.
>>
>
> I'm undecided on these.  They would obviously be useful, but on the other 
> hand minimalism has its virtues.  In the base case of reading code with a 
> plaintext editor, I usually find embedded doco with lots of markup annoying 
> and an impediment to code reading.  I think I'm inclined to favor keeping 
> markup out of code but I'm keeping an open mind about it.
>

Gregg,

I strongly opposed the introduction of case-sensitive identifiers in R6RS 
Scheme. Case-insensitive identifiers allow programmers to write comments 
and documentation that unambiguously refer to arguments and function names 
in ALL-CAPS. As a bonus, a sentence need never begin with a capital letter, 
even if one is using something like back-ticks to indicate monospaced type, 
because `All-caps` is an equally valid representation. There are legitimate 
reasons to embrace case-sensitive identifiers, but the happy interplay 
between pre-R5RS source code and the written word was lost.

In Clojure doc strings, I either pretend that identifiers are 
case-insensitive or use back-ticks and try very hard not to start sentences 
with lower-case identifiers. Regarding code itself, I tend to use all-caps 
identifiers for macro arguments, another common Scheme (and Lisp?) 
convention, to make it more clear what's going on during quasi-quoting.

Edwin

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[bob]

Any Result? Talk is cheap

On Sunday, April 27, 2014 12:39:04 AM UTC+8, Val Waeselynck wrote:
>
> Hello to all,
>
> *Short version :* I think Clojure needs a documentation system in 
> Clojure, I would like to know if some efforts exist in that direction, and 
> I am willing to create it / contribute to it.
>
> *Long version :*
>
> I've been thinking for a while that the Clojure community could benefit a 
> lot from a more sophisticated and ergonomic documentation system. 
>
> I have seen some existing plugins like lein-sphinx, but I think it would 
> be really good to have documentation that would be written in Clojure, for 
> the following reasons :
>
>- we're all very fond of Clojure data structures and their syntax. (I 
>don't know about you, but I find that even HTML looks better in 
> Clojurethan in HTML). Plus, Clojure 
> programmers already know how to edit them.
>- (better reason) The facts that Vars are first-class citizens and 
>that symbols can be referred explicitly with hardly any ceremony (macros) 
>are a exceptional opportunity to make smart and highly-structured 
>documentation very easily.
>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
> hoc*documentation functionality on top of it to suit their own particular 
> needs.
>
> I haven't found anything of the like yet, and if it exists, I would be 
> grateful if someone would redirect me to it.
>
> Here are *my thoughts on this :*
>
>1. Clojure doc-strings, although they are quite handy as reminders and 
>for doc-indexation, are *too raw a content*. Even when they are done 
>right, they tend to be cumbersome, and it's too bad to have such concise 
>code drown in the middle of so much documentation. What's more, I believe 
>that when programmers program a function (or anything), they tend to think 
>more about the implementation than the (uninformed) usage, so they have 
>little incentive to make it right.
>2. Building on 1. having a system where documentation and programs 
>live in separate files, in the same way as tests, would enforce a healthy 
>separation of concerns. Importantly, it would make life much easier on the 
>Version Control perspective.
>3. Documentation should probably be made differently than what people 
>have got accustomed to by classical languages. Because you seldom find 
>types, and because IMHO Clojure programs are formed more by factoring out 
>recurring mechanisms in code than from implementing intellectual 
>abstractions, the relevant concepts tend not to be obvious in the code. 
>Since in Clojure we program with verbs, not 
> nouns,
>  
>I think *documentation is best made by example*.
>4. Documentation of a Var should not be a formal description of what 
>it is and what it does with some cryptically-named variables. *Every 
>bit of documentation should be a micro-tutorial*. Emphasis should be 
>put on usage, examples, tips, pitfalls, howtos.
>5. There should be structure in the documentation, and it shouldn't be 
>just :see-also links - *there should be semantics* in it.  For 
>example, some functions/macros are really meant to be nothing but 
>shorthands for calling other functions : that kind of relationship should 
>be explicitly documented.
>6. Documentation should not be just information about each separate 
>Var in a namespace. There should be a hierarchy to make the most useful 
>elements of an API more obvious. Also, adding cross-vars documentation 
>elements such as tags and topics could make it easier to navigate and 
>understand.
>7. *Documentation in the REPL is great*, it was one of the very good 
>surprises when I started learning Clojure. However, a rich and 
> good-looking 
>presentation like in Javadocs would be welcome too.
>
> Of course, all of the above are just vague principles. Here is *some 
> functionality I suggest for a start :*
>
>1. Documentation content elements could be written in a Clojure DSL 
>emulating some kind of docbook-like markup language.
>2. On the user side, the documentation would be accessible through a 
>generated web interface, a REPL interface, and maybe other formats like 
>Wiki.
>3. Documentation could be programmed anywhere in a project by simply 
>referring to the relevant Vars and calling the documentation API. Ideally, 
>there would be a dedicated folder for documentation files, and a Leiningen 
>plugin to compile them and generate the HTML from them.
>4. I often find myself lost because I have no idea what shape some 
>arguments to a function should have, such as config maps and maps 
>representing application-specific models. To adress this, I propose to 
>explicitly declare and describe *"stereotypes"* in

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

I added some stuff on the Elisp documentation. Others can update if they
think I am wrong!

Phil

Val Waeselynck  writes:
> So it would be nice if people who are knowledgeable about other doc systems 
> could contribute to it. From what I see, that may involve Tim for Emacs, 
> Sean for reStructured, and Daniel for docco, for example?
>
> Thanks in advance!
>
> Le samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit :
>>
>> Hello to all,
>>
>> *Short version :* I think Clojure needs a documentation system in 
>> Clojure, I would like to know if some efforts exist in that direction, and 
>> I am willing to create it / contribute to it.
>>
>> *Long version :*
>>
>> I've been thinking for a while that the Clojure community could benefit a 
>> lot from a more sophisticated and ergonomic documentation system. 
>>
>> I have seen some existing plugins like lein-sphinx, but I think it would 
>> be really good to have documentation that would be written in Clojure, for 
>> the following reasons :
>>
>>- we're all very fond of Clojure data structures and their syntax. (I 
>>don't know about you, but I find that even HTML looks better in
>> Clojurethan in HTML). Plus, Clojure
>> programmers already know how to edit them.
>>- (better reason) The facts that Vars are first-class citizens and 
>>that symbols can be referred explicitly with hardly any ceremony (macros) 
>>are a exceptional opportunity to make smart and highly-structured 
>>documentation very easily.
>>- if it's in Clojure, Clojure programmers can seamlessly build *ad
>> hoc*documentation functionality on top of it to suit their own particular
>> needs.
>>
>> I haven't found anything of the like yet, and if it exists, I would be 
>> grateful if someone would redirect me to it.
>>
>> Here are *my thoughts on this :*
>>
>>1. Clojure doc-strings, although they are quite handy as reminders and 
>>for doc-indexation, are *too raw a content*. Even when they are done 
>>right, they tend to be cumbersome, and it's too bad to have such concise 
>>code drown in the middle of so much documentation. What's more, I believe 
>>that when programmers program a function (or anything), they tend to 
>> think 
>>more about the implementation than the (uninformed) usage, so they have 
>>little incentive to make it right.
>>2. Building on 1. having a system where documentation and programs 
>>live in separate files, in the same way as tests, would enforce a healthy 
>>separation of concerns. Importantly, it would make life much easier on 
>> the 
>>Version Control perspective.
>>3. Documentation should probably be made differently than what people 
>>have got accustomed to by classical languages. Because you seldom find 
>>types, and because IMHO Clojure programs are formed more by factoring out 
>>recurring mechanisms in code than from implementing intellectual 
>>abstractions, the relevant concepts tend not to be obvious in the code. 
>>Since in Clojure we program with verbs, not
>> nouns,
>>I think *documentation is best made by example*.
>>4. Documentation of a Var should not be a formal description of what 
>>it is and what it does with some cryptically-named variables. *Every 
>>bit of documentation should be a micro-tutorial*. Emphasis should be 
>>put on usage, examples, tips, pitfalls, howtos.
>>5. There should be structure in the documentation, and it shouldn't be 
>>just :see-also links - *there should be semantics* in it.  For 
>>example, some functions/macros are really meant to be nothing but 
>>shorthands for calling other functions : that kind of relationship should 
>>be explicitly documented.
>>6. Documentation should not be just information about each separate 
>>Var in a namespace. There should be a hierarchy to make the most useful 
>>elements of an API more obvious. Also, adding cross-vars documentation 
>>elements such as tags and topics could make it easier to navigate and 
>>understand.
>>7. *Documentation in the REPL is great*, it was one of the very good 
>>surprises when I started learning Clojure. However, a rich and 
>> good-looking 
>>presentation like in Javadocs would be welcome too.
>>
>> Of course, all of the above are just vague principles. Here is *some 
>> functionality I suggest for a start :*
>>
>>1. Documentation content elements could be written in a Clojure DSL 
>>emulating some kind of docbook-like markup language.
>>2. On the user side, the documentation would be accessible through a 
>>generated web interface, a REPL interface, and maybe other formats like 
>>Wiki.
>>3. Documentation could be programmed anywhere in a project by simply 
>>referring to the relevant Vars and calling the documentation API. 
>> Ideally,

Re: Proposing a new Clojure documentation system (in Clojure)

[Sean Johnson]

>
> So it would be nice if people who are knowledgeable about other doc 
> systems could contribute to it. From what I see, that may involve Tim for 
> Emacs, Sean for reStructured, and Daniel for docco, for example?
>

I took the liberty of fleshing out the 
documenta
 bit, and I added sections for reStructuredText/Sphinx/ReadTheDocs.org and 
codox.

Cheers,
Sean

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Andy Fingerhut]

It is pretty easy to make a library that modifies doc metadata on existing
vars, e.g.:

https://github.com/jafingerhut/thalia

The time-consuming part, which I am nowhere near completing myself, is
writing the alternate documentation strings.  Congrats to anyone that
produces something that becomes widely used.

I would suggest doing whatever suits your fancy in this area, preferably
with no support required, nor roadblocks in the way of what you plan to do,
from clojure.core.  Don't be surprised if all your rallying efforts lead to
a team of size one :-)

Andy


On Sat, May 10, 2014 at 7:09 AM, Timothy Baldridge wrote:

> If you plan on having this documentation apply to clojure.core.* you'll
> probably want to pull in Alex Miller or start a conversation in
> clojure-dev. I'd hate to see a bunch of decisions made, just to find out
> that Rich has a completely different view, a view that might have been nice
> to know before plans were finalized.
>
> Or perhaps a metadata modification system can be created? One that allows
> people to import clojure libs that adds new doc data to existing vars?
>
> Timothy
>
>
> On Sat, May 10, 2014 at 7:44 AM, Val Waeselynck wrote:
>
>> Here 
>> :I
>>  think it would help if we had a panoramic view of the existing
>> documentation systems and what we could borrow from them. I could only
>> think of a Google Drive spreadsheet for this, but if anyone has a better
>> idea... :)
>>
>> So it would be nice if people who are knowledgeable about other doc
>> systems could contribute to it. From what I see, that may involve Tim for
>> Emacs, Sean for reStructured, and Daniel for docco, for example?
>>
>> Thanks in advance!
>>
>> Le samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit :
>>
>>> Hello to all,
>>>
>>> *Short version :* I think Clojure needs a documentation system in
>>> Clojure, I would like to know if some efforts exist in that direction, and
>>> I am willing to create it / contribute to it.
>>>
>>> *Long version :*
>>>
>>> I've been thinking for a while that the Clojure community could benefit
>>> a lot from a more sophisticated and ergonomic documentation system.
>>>
>>> I have seen some existing plugins like lein-sphinx, but I think it would
>>> be really good to have documentation that would be written in Clojure, for
>>> the following reasons :
>>>
>>>- we're all very fond of Clojure data structures and their syntax.
>>>(I don't know about you, but I find that even HTML looks better in
>>>Clojure  than in HTML). Plus,
>>>Clojure programmers already know how to edit them.
>>>- (better reason) The facts that Vars are first-class citizens and
>>>that symbols can be referred explicitly with hardly any ceremony (macros)
>>>are a exceptional opportunity to make smart and highly-structured
>>>documentation very easily.
>>>- if it's in Clojure, Clojure programmers can seamlessly build *ad
>>>hoc* documentation functionality on top of it to suit their own
>>>particular needs.
>>>
>>> I haven't found anything of the like yet, and if it exists, I would be
>>> grateful if someone would redirect me to it.
>>>
>>> Here are *my thoughts on this :*
>>>
>>>1. Clojure doc-strings, although they are quite handy as reminders
>>>and for doc-indexation, are *too raw a content*. Even when they are
>>>done right, they tend to be cumbersome, and it's too bad to have such
>>>concise code drown in the middle of so much documentation. What's more, I
>>>believe that when programmers program a function (or anything), they tend
>>>to think more about the implementation than the (uninformed) usage, so 
>>> they
>>>have little incentive to make it right.
>>>2. Building on 1. having a system where documentation and programs
>>>live in separate files, in the same way as tests, would enforce a healthy
>>>separation of concerns. Importantly, it would make life much easier on 
>>> the
>>>Version Control perspective.
>>>3. Documentation should probably be made differently than what
>>>people have got accustomed to by classical languages. Because you seldom
>>>find types, and because IMHO Clojure programs are formed more by 
>>> factoring
>>>out recurring mechanisms in code than from implementing intellectual
>>>abstractions, the relevant concepts tend not to be obvious in the code.
>>>Since in Clojure we program with verbs, not 
>>> nouns,
>>>I think *documentation is best made by example*.
>>>4. Documentation of a Var should not be a formal description of what
>>>it is and what it does with some cryptically-named variables. *Every
>>>bit of documentation should be a micro-tutorial*. Emphasis should be
>>>put on usage, examples, tips, pitfalls, how

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

Le samedi 10 mai 2014 16:09:11 UTC+2, tbc++ a écrit :
>
> If you plan on having this documentation apply to clojure.core.* you'll 
> probably want to pull in Alex Miller or start a conversation in 
> clojure-dev. I'd hate to see a bunch of decisions made, just to find out 
> that Rich has a completely different view, a view that might have been nice 
> to know before plans were finalized. 
>
> Or perhaps a metadata modification system can be created? One that allows 
> people to import clojure libs that adds new doc data to existing vars?
>

Actually, I was thinking of making something that is completely external to 
the metadata map, so as to make it nonintrusive. A bit like a test library.
 

>
> Timothy
>
>
> On Sat, May 10, 2014 at 7:44 AM, Val Waeselynck 
> 
> > wrote:
>
>> Here 
>> :I
>>  think it would help if we had a panoramic view of the existing 
>> documentation systems and what we could borrow from them. I could only 
>> think of a Google Drive spreadsheet for this, but if anyone has a better 
>> idea... :)
>>
>> So it would be nice if people who are knowledgeable about other doc 
>> systems could contribute to it. From what I see, that may involve Tim for 
>> Emacs, Sean for reStructured, and Daniel for docco, for example?
>>
>> Thanks in advance!
>>
>> Le samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit :
>>
>>> Hello to all,
>>>
>>> *Short version :* I think Clojure needs a documentation system in 
>>> Clojure, I would like to know if some efforts exist in that direction, and 
>>> I am willing to create it / contribute to it.
>>>
>>> *Long version :*
>>>
>>> I've been thinking for a while that the Clojure community could benefit 
>>> a lot from a more sophisticated and ergonomic documentation system. 
>>>
>>> I have seen some existing plugins like lein-sphinx, but I think it would 
>>> be really good to have documentation that would be written in Clojure, for 
>>> the following reasons :
>>>
>>>- we're all very fond of Clojure data structures and their syntax. 
>>>(I don't know about you, but I find that even HTML looks better in 
>>>Clojure  than in HTML). Plus, 
>>>Clojure programmers already know how to edit them.
>>>- (better reason) The facts that Vars are first-class citizens and 
>>>that symbols can be referred explicitly with hardly any ceremony 
>>> (macros) 
>>>are a exceptional opportunity to make smart and highly-structured 
>>>documentation very easily. 
>>>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
>>>hoc* documentation functionality on top of it to suit their own 
>>>particular needs.
>>>
>>> I haven't found anything of the like yet, and if it exists, I would be 
>>> grateful if someone would redirect me to it.
>>>
>>> Here are *my thoughts on this :*
>>>
>>>1. Clojure doc-strings, although they are quite handy as reminders 
>>>and for doc-indexation, are *too raw a content*. Even when they are 
>>>done right, they tend to be cumbersome, and it's too bad to have such 
>>>concise code drown in the middle of so much documentation. What's more, 
>>> I 
>>>believe that when programmers program a function (or anything), they 
>>> tend 
>>>to think more about the implementation than the (uninformed) usage, so 
>>> they 
>>>have little incentive to make it right.
>>>2. Building on 1. having a system where documentation and programs 
>>>live in separate files, in the same way as tests, would enforce a 
>>> healthy 
>>>separation of concerns. Importantly, it would make life much easier on 
>>> the 
>>>Version Control perspective. 
>>>3. Documentation should probably be made differently than what 
>>>people have got accustomed to by classical languages. Because you seldom 
>>>find types, and because IMHO Clojure programs are formed more by 
>>> factoring 
>>>out recurring mechanisms in code than from implementing intellectual 
>>>abstractions, the relevant concepts tend not to be obvious in the code. 
>>>Since in Clojure we program with verbs, not 
>>> nouns,
>>>  
>>>I think *documentation is best made by example*.
>>>4. Documentation of a Var should not be a formal description of what 
>>>it is and what it does with some cryptically-named variables. *Every 
>>>bit of documentation should be a micro-tutorial*. Emphasis should be 
>>>put on usage, examples, tips, pitfalls, howtos. 
>>>5. There should be structure in the documentation, and it shouldn't 
>>>be just :see-also links - *there should be semantics* in it.  For 
>>>example, some functions/macros are really meant to be nothing but 
>>>shorthands for calling other functions : that kind of relationship 
>>> should 
>>>be explicitly

Re: Proposing a new Clojure documentation system (in Clojure)

[Timothy Baldridge]

If you plan on having this documentation apply to clojure.core.* you'll
probably want to pull in Alex Miller or start a conversation in
clojure-dev. I'd hate to see a bunch of decisions made, just to find out
that Rich has a completely different view, a view that might have been nice
to know before plans were finalized.

Or perhaps a metadata modification system can be created? One that allows
people to import clojure libs that adds new doc data to existing vars?

Timothy


On Sat, May 10, 2014 at 7:44 AM, Val Waeselynck wrote:

> Here 
> :I
>  think it would help if we had a panoramic view of the existing
> documentation systems and what we could borrow from them. I could only
> think of a Google Drive spreadsheet for this, but if anyone has a better
> idea... :)
>
> So it would be nice if people who are knowledgeable about other doc
> systems could contribute to it. From what I see, that may involve Tim for
> Emacs, Sean for reStructured, and Daniel for docco, for example?
>
> Thanks in advance!
>
> Le samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit :
>
>> Hello to all,
>>
>> *Short version :* I think Clojure needs a documentation system in
>> Clojure, I would like to know if some efforts exist in that direction, and
>> I am willing to create it / contribute to it.
>>
>> *Long version :*
>>
>> I've been thinking for a while that the Clojure community could benefit a
>> lot from a more sophisticated and ergonomic documentation system.
>>
>> I have seen some existing plugins like lein-sphinx, but I think it would
>> be really good to have documentation that would be written in Clojure, for
>> the following reasons :
>>
>>- we're all very fond of Clojure data structures and their syntax. (I
>>don't know about you, but I find that even HTML looks better in
>>Clojure  than in HTML). Plus,
>>Clojure programmers already know how to edit them.
>>- (better reason) The facts that Vars are first-class citizens and
>>that symbols can be referred explicitly with hardly any ceremony (macros)
>>are a exceptional opportunity to make smart and highly-structured
>>documentation very easily.
>>- if it's in Clojure, Clojure programmers can seamlessly build *ad
>>hoc* documentation functionality on top of it to suit their own
>>particular needs.
>>
>> I haven't found anything of the like yet, and if it exists, I would be
>> grateful if someone would redirect me to it.
>>
>> Here are *my thoughts on this :*
>>
>>1. Clojure doc-strings, although they are quite handy as reminders
>>and for doc-indexation, are *too raw a content*. Even when they are
>>done right, they tend to be cumbersome, and it's too bad to have such
>>concise code drown in the middle of so much documentation. What's more, I
>>believe that when programmers program a function (or anything), they tend
>>to think more about the implementation than the (uninformed) usage, so 
>> they
>>have little incentive to make it right.
>>2. Building on 1. having a system where documentation and programs
>>live in separate files, in the same way as tests, would enforce a healthy
>>separation of concerns. Importantly, it would make life much easier on the
>>Version Control perspective.
>>3. Documentation should probably be made differently than what people
>>have got accustomed to by classical languages. Because you seldom find
>>types, and because IMHO Clojure programs are formed more by factoring out
>>recurring mechanisms in code than from implementing intellectual
>>abstractions, the relevant concepts tend not to be obvious in the code.
>>Since in Clojure we program with verbs, not 
>> nouns,
>>I think *documentation is best made by example*.
>>4. Documentation of a Var should not be a formal description of what
>>it is and what it does with some cryptically-named variables. *Every
>>bit of documentation should be a micro-tutorial*. Emphasis should be
>>put on usage, examples, tips, pitfalls, howtos.
>>5. There should be structure in the documentation, and it shouldn't
>>be just :see-also links - *there should be semantics* in it.  For
>>example, some functions/macros are really meant to be nothing but
>>shorthands for calling other functions : that kind of relationship should
>>be explicitly documented.
>>6. Documentation should not be just information about each separate
>>Var in a namespace. There should be a hierarchy to make the most useful
>>elements of an API more obvious. Also, adding cross-vars documentation
>>elements such as tags and topics could make it easier to navigate and
>>understand.
>>7. *Documentation in the REPL is great*, it was one of the very good
>>  

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

Here 
:I
 think it would help if we had a panoramic view of the existing 
documentation systems and what we could borrow from them. I could only 
think of a Google Drive spreadsheet for this, but if anyone has a better 
idea... :)

So it would be nice if people who are knowledgeable about other doc systems 
could contribute to it. From what I see, that may involve Tim for Emacs, 
Sean for reStructured, and Daniel for docco, for example?

Thanks in advance!

Le samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit :
>
> Hello to all,
>
> *Short version :* I think Clojure needs a documentation system in 
> Clojure, I would like to know if some efforts exist in that direction, and 
> I am willing to create it / contribute to it.
>
> *Long version :*
>
> I've been thinking for a while that the Clojure community could benefit a 
> lot from a more sophisticated and ergonomic documentation system. 
>
> I have seen some existing plugins like lein-sphinx, but I think it would 
> be really good to have documentation that would be written in Clojure, for 
> the following reasons :
>
>- we're all very fond of Clojure data structures and their syntax. (I 
>don't know about you, but I find that even HTML looks better in 
> Clojurethan in HTML). Plus, Clojure 
> programmers already know how to edit them.
>- (better reason) The facts that Vars are first-class citizens and 
>that symbols can be referred explicitly with hardly any ceremony (macros) 
>are a exceptional opportunity to make smart and highly-structured 
>documentation very easily.
>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
> hoc*documentation functionality on top of it to suit their own particular 
> needs.
>
> I haven't found anything of the like yet, and if it exists, I would be 
> grateful if someone would redirect me to it.
>
> Here are *my thoughts on this :*
>
>1. Clojure doc-strings, although they are quite handy as reminders and 
>for doc-indexation, are *too raw a content*. Even when they are done 
>right, they tend to be cumbersome, and it's too bad to have such concise 
>code drown in the middle of so much documentation. What's more, I believe 
>that when programmers program a function (or anything), they tend to think 
>more about the implementation than the (uninformed) usage, so they have 
>little incentive to make it right.
>2. Building on 1. having a system where documentation and programs 
>live in separate files, in the same way as tests, would enforce a healthy 
>separation of concerns. Importantly, it would make life much easier on the 
>Version Control perspective.
>3. Documentation should probably be made differently than what people 
>have got accustomed to by classical languages. Because you seldom find 
>types, and because IMHO Clojure programs are formed more by factoring out 
>recurring mechanisms in code than from implementing intellectual 
>abstractions, the relevant concepts tend not to be obvious in the code. 
>Since in Clojure we program with verbs, not 
> nouns,
>  
>I think *documentation is best made by example*.
>4. Documentation of a Var should not be a formal description of what 
>it is and what it does with some cryptically-named variables. *Every 
>bit of documentation should be a micro-tutorial*. Emphasis should be 
>put on usage, examples, tips, pitfalls, howtos.
>5. There should be structure in the documentation, and it shouldn't be 
>just :see-also links - *there should be semantics* in it.  For 
>example, some functions/macros are really meant to be nothing but 
>shorthands for calling other functions : that kind of relationship should 
>be explicitly documented.
>6. Documentation should not be just information about each separate 
>Var in a namespace. There should be a hierarchy to make the most useful 
>elements of an API more obvious. Also, adding cross-vars documentation 
>elements such as tags and topics could make it easier to navigate and 
>understand.
>7. *Documentation in the REPL is great*, it was one of the very good 
>surprises when I started learning Clojure. However, a rich and 
> good-looking 
>presentation like in Javadocs would be welcome too.
>
> Of course, all of the above are just vague principles. Here is *some 
> functionality I suggest for a start :*
>
>1. Documentation content elements could be written in a Clojure DSL 
>emulating some kind of docbook-like markup language.
>2. On the user side, the documentation would be accessible through a 
>generated web interface, a REPL interface, and maybe other formats like 
>Wiki.
>3. Documentation could be programme

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

We can see from this discussion that several strongly opinionated visions 
of what documentation should be coexist. Some want literate programming 
whereas others want to avoid it, some want something that looks like 
javadoc, some just want markdown, etc.

I think we can just make room for all of these views. Let's start by 
providing functionality for creating and viewing neutral, structured, 
extensible documentation content. I think both Markdown and raw strings are 
too weak for that; I'd rather make a more sophisticated language/data 
structure and then translate Markdown or docstrings or whatever into it. 
Then we can create more pleasant programmatic interfaces on top of it, to 
achieve the goals of simplicity and of the more opinionated paradigms. 

That's my reason for wanting to make this in Clojure data structures in the 
first place; as long as we have the benefits of Clojure's great programming 
features, we can mostly avoid having to make tradeoffs between available 
functionality and desired usage, and that's *good*.

Let's not make anything opinionated mandatory or standard until usage has 
proven it.

Also, I agree that we need better formalism and categorization for 
reasoning about technical documentation. Very good things were said in the Deep 
Thinkingthread
 on this topic. I see there are a few books in the field, I'll try to 
dig into these.

Le mercredi 7 mai 2014 05:16:16 UTC+2, da...@axiom-developer.org a écrit :
>
> Gregg, 
>
> I realize that literate programming isn't going to catch on in the 
> Clojure community any time soon. LP shared the "epiphany" feature 
> of Lisp. That is, you don't "get it" until the "AH HA!" moment, 
> and then you wonder why anyone programs any other way. You can't get 
> the Lisp AH HA! without writing Lisp, so many Java programmers will 
> never "get" Clojure. You can't get LP without writing LP, so many 
> programmers will never get LP. Oh well. I am trying to refocus on the 
> goal of "deep thinking" the documentation problem in Clojure. 
>
>
>
> My more recent posts have moved on from LP and have been focused on 
> finding criteria to judge whether proposed solutions actually address 
> useful goals. Parent tried to do that in his thesis. See my prior post. 
>
> There are many different audiences that need Clojure documentation. Some 
> are core maintainers who have to understand the Java code. Some are 
> programmers who need to understand the language. Some are library 
> maintainers who need to explain their use case. Some are people who join 
> a company using Clojure. Some are language designers who need to 
> understand principles like immutability, simplicity, STM, etc. 
>
> There are thousands of useful programs in github. Most of them are 
> dead because the original programmers are gone and nobody knows their 
> use case nor how to maintain and modify them. Once the original team 
> moves on even popular projects die. Even programs written by famous 
> people with huge amounts of influence die. Witness Arc by Paul Graham, 
> or Pascal which took over the world in the last century. Without Rich, 
> wither Clojure? 
>
> I really like Clojure and I want it to live. I believe that unless 
> we focus SOME effort on making it easy to maintain, modify, use, and 
> understand then Clojure will suffer the fate of Pascal, Arc, and that ilk. 
>
>
>
>
>
> >  To my knowledge neither 
> > Knuth nor anybody else has ever produced a shred of evidence in support 
> of 
> > this kind of claim. 
>
> I can't speak to your knowledge but there are numerous examples. As to 
> the cited stackoverflow claim that LP is not used in projects or 
> teaching... 
>
> Here is PROJECT example from SAGE, a python-based computer algebra 
> system in Number Theory: 
>
> "Another thing I've been enjoying lately is literate programming. 
>  Amazingly it turns out to be faster to write a literate program 
>  than an ordinary program because debugging takes almost no time." 
>
> -- Bill Hart, SAGE Mailing list, May 3, 2010 
>
> Here is a TEACHING example from Spring 2014: 
>
> John Kitchin is a professor of Chemical Engineering at CMU.  He is 
> teaching CMU students to use literate programming and uses it in all of 
> his courses. He recently gave a talk at PyCon 
>
> http://www.youtube.com/watch?v=1-dUkyn_fZA 
>
>
>
>
> > Are you saying the core Clojure team is 
> rewriting 
> > Clojure in *classic* litprog style?  That would flabber my gast, to put 
> it 
> > mildly. 
>
> No, "the core Clojure team" is NOT rewriting Clojure in *classic* 
> litprog style. I am, with the help of others. See 
> PDF: http://daly.axiom-developer.org/clojure.pdf 
> SRC: http://daly.axiom-developer.org/clojure.pamphlet 
>
> If you follow the instructions you can type 'make' which extracts 
> Clojure source code, compile

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Gregg Reynolds  writes:

> On Tue, May 6, 2014 at 10:11 AM, Phillip Lord
> wrote:
>
>> True, and, to some extent, it inherits the ";" vs ";;" comment
>> distinction. But, again, there is not structure. This is an unstructured
>> string also. Compare Emacs Lisp, for example, which uses semi-structure
>> in the comments to drive many of its features.
>>
>
> I'm ok with some kind of structure for comments and docstrings, but I would
> relegate it to an add-on, not part of the Clojure language definition.
> We're effectively talking about adding a second syntax.  The original
> poster (Val?) suggested using Clojure syntax for the documentation
> language, but I'm not so sure about that yet; haven't thought about it
> enough. 


What we need and how we get it are two different things of course.
Should the documentation be in the language definition? Well, the
language needs to *support* it.

In Java, we have /** */ to support javadoc.

In terms of clojure documentation, we can already use clojure syntax for
the documentation. For instance:

(defn ^{:doc (str "hello " [] " list")}
  testfn [])

Of course, this loses all structure once the form is evaled, but you can
see what I mean. If we allow

(defn ^{doc (fn [] (str "documentation"))} testfn[])

then we have a whole new ball game. The documentation can do what ever
we want, including for example lazy loading of documentation that is
complex and which would otherwise slow loading.

>> I've used this example before; consider this unstructured string from
>> `cons`.
>>
>> Returns a new seq where x is the first element and seq is
>> the rest.
>>
>>
>> So, cons returns a seq where x is the first element, and seq is the
>> rest? Which means that cons returns the same (constantly x) for which
>> (rest (constantly x)) could be said to equal (constantly x), as a
>> infinite string of x's is the same as an infinite string of x's one
>> shorter.
>>
>
> I would call that an example of sloppy documentation since it uses "seq" as
> both a type name and a data name.  Support for structured strings can't
> prevent that.

Here is the documentation from Emacs.

(cons CAR CDR)

Create a new cons, give it CAR and CDR as components, and return it.

It's got it's problems but being unable to distinguish between CAR the
function and CAR the parameter is not one of them.


> seq xs -> x::xs  ;; by convention, 'xs' means 'collection of somethings'
> and 'x::xs' means "sequence of somethings"
> seq nil -> nil
>
> I guess the point is that good, clear, concise, well-defined conventions
> can solve a lot of problems before we even get to the issue of supporting
> structured doc text.

I think all of this is good. You'll notice that the Emacs solution uses
a typographical convention -- very thin structuring.


>> I was never a great fan of writing XML by hand, to be honest (which is
>> what this appears to be). The first example that I looked at:
>>
>> https://github.com/mobileink/leiningen-doc/blob/master/ug/classpath.dita
>>
>> incidentally, appears to be ill-formed, having two "" tags.
>>
>
> I only see one.  Anyway, the processor didn't object.

Oops. "conbody" and "concept".

>> XML is hard to write.
>>
>
> YMMV; I find it easy to write.  To me, XML is no different than any other
> language: if you work with it enough, it becomes second nature.  I use
> emacs + nxml + yasnippet and would not dream of editing xml in any other
> way.  Then again I do a lot of xml editing, and I'm happy as a clam with
> nothing more than bash, emacs, and manpages, which makes me a throwback, I
> suppose.

This is true, I guess, although I do find XML rather verbose; ironic,
given that you were complaining about structuring making things hard to
read earlier!


>> Documentation is about scalability; it only hits when you have a
>> reasonable amount of code (especially external libraries). It also hits
>> newcomers most.
>>
>> So, perhaps, the time is now.
>>
>
> If not now, when?  If not me, who?  Answer: somebody else, I hope.

A noble sentiment! I can only agree.

Phil

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Tim Daly  writes:
>- include diagrams and pictures
>It is easy to show the red-black tree rebalance algorithm
>  with a few pictures whereas the words are rather opaque. 
>  Stacks and immutable copy algorithms are also easy in diagrams.
>  You CAN do this with "ascii-art" but it IS the late 90s and some
>  lucky few of us have 640x480 color terminals.


Yes, I agree with this, images would be nice.

Phil

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Sean Corfield  writes:
> On May 6, 2014, at 8:11 AM, Phillip Lord  wrote:
>> I've used this example before; consider this unstructured string from
>> `cons`.
>> 
>> Returns a new seq where x is the first element and seq is
>> the rest.
>
> Just because one (or several) of the clojure.core function docstrings are
> poorly written, doesn't mean Clojure's current documentation system is broken.
> This simply comes back to developers needing to write _better_ documentation,
> not _more_ documentation.

Indeed, and the need for some standards comes from this. Let's rewrite
the cons docstring so my (perverse) interpretation cannot hold.

  Returns a new seq where the value of the parameter x is the first
  element and the value of the parameter seq is the rest.

Now, this is more correct, but hard to read.

This is why we need (at least) some standard markup in doc strings. The
Emacs style

  Returns a new seq where X is the first element and SEQ is the rest.

Better, I think would be:

  Returns a new seq where X is the first element and SEQ is the rest.
  See also: seq, seq?, first, rest

And then add

  Returns a new seq where X is the first element and SEQ is the rest.
  See also: `seq', `seq?', `first', `rest'
  http://clojure.org/sequences


These are small changes, no revolutionary ones. Literate programming or
otherwise is an interesting discussion, but at least getting up to the
level of Emacs (a 20 year old lisp!) would be good.

If you think I am wrong, then show me *any* book on programming that
uses no typography to distinguish semantically different parts of the
document.


> Adding complexity and weaving heapings of prose in amongst the code isn't
> going to make the developer that wrote the above rewrite it in a better way.
> You'll just end up with more bad documentation getting in the way of what the
> code actually does. Bad documentation is worse than no documentation. At least
> with no documentation, the code doesn't lie.


The "use the source, Luke" argument is a good one in some cases.
In this case, though, this is the source.

(def
 ^{:arglists '([x seq])
:doc "Returns a new seq where x is the first element and seq is
the rest."
   :added "1.0"
   :static true}

 cons (fn* ^:static cons [x seq] (. clojure.lang.RT (cons x seq

So, not that helpful. You can, of course, look up RT.java if you know
the "." notation (which you might not, because it's not meant for normal
use).

which brings you to this...

static public ISeq cons(Object x, Object coll){
//ISeq y = seq(coll);
if(coll == null)
return new PersistentList(x);
else if(coll instanceof ISeq)
return new Cons(x, (ISeq) coll);
else
return new Cons(x, seq(coll));
}

which is not documented at all and which is defined to be an
implementation detail.

So, no the code doesn't lie, but it doesn't necessarily tell you much
either.

Phil

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Akos Gyimesi]

On Tue, May 6, 2014, at 07:54 PM, Timothy Baldridge wrote:

>> Clojure is being reworked into literate form already

Proof of this claim?


I think Tim referred to his personal project to convert Clojure code
into a literate form:
[1]https://groups.google.com/forum/#!topic/clojure/RgQX_kXzFMM

References

1. https://groups.google.com/forum/#!topic/clojure/RgQX_kXzFMM

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[u1204]

Gregg,

I realize that literate programming isn't going to catch on in the
Clojure community any time soon. LP shared the "epiphany" feature
of Lisp. That is, you don't "get it" until the "AH HA!" moment,
and then you wonder why anyone programs any other way. You can't get
the Lisp AH HA! without writing Lisp, so many Java programmers will
never "get" Clojure. You can't get LP without writing LP, so many
programmers will never get LP. Oh well. I am trying to refocus on the
goal of "deep thinking" the documentation problem in Clojure.



My more recent posts have moved on from LP and have been focused on
finding criteria to judge whether proposed solutions actually address
useful goals. Parent tried to do that in his thesis. See my prior post.

There are many different audiences that need Clojure documentation. Some
are core maintainers who have to understand the Java code. Some are
programmers who need to understand the language. Some are library
maintainers who need to explain their use case. Some are people who join
a company using Clojure. Some are language designers who need to
understand principles like immutability, simplicity, STM, etc.

There are thousands of useful programs in github. Most of them are
dead because the original programmers are gone and nobody knows their
use case nor how to maintain and modify them. Once the original team
moves on even popular projects die. Even programs written by famous
people with huge amounts of influence die. Witness Arc by Paul Graham,
or Pascal which took over the world in the last century. Without Rich,
wither Clojure?

I really like Clojure and I want it to live. I believe that unless
we focus SOME effort on making it easy to maintain, modify, use, and
understand then Clojure will suffer the fate of Pascal, Arc, and that ilk.





>  To my knowledge neither
> Knuth nor anybody else has ever produced a shred of evidence in support of
> this kind of claim.

I can't speak to your knowledge but there are numerous examples. As to
the cited stackoverflow claim that LP is not used in projects or teaching...

Here is PROJECT example from SAGE, a python-based computer algebra
system in Number Theory:

"Another thing I've been enjoying lately is literate programming. 
 Amazingly it turns out to be faster to write a literate program 
 than an ordinary program because debugging takes almost no time."

-- Bill Hart, SAGE Mailing list, May 3, 2010

Here is a TEACHING example from Spring 2014:

John Kitchin is a professor of Chemical Engineering at CMU.  He is
teaching CMU students to use literate programming and uses it in all of
his courses. He recently gave a talk at PyCon

http://www.youtube.com/watch?v=1-dUkyn_fZA




> Are you saying the core Clojure team is rewriting
> Clojure in *classic* litprog style?  That would flabber my gast, to put it
> mildly.

No, "the core Clojure team" is NOT rewriting Clojure in *classic*
litprog style. I am, with the help of others. See
PDF: http://daly.axiom-developer.org/clojure.pdf
SRC: http://daly.axiom-developer.org/clojure.pamphlet

If you follow the instructions you can type 'make' which extracts
Clojure source code, compiles it, extracts and runs the test cases,
and puts you into a REPL. It also re-creates the PDF. The whole
process takes under a minute. LP is trivial to learn and use.

The cycle is to edit the file (code or natural language), type
'make', and your new code is built, tested, and ready to run. At
the same time the PDF of the book is recreated from the same source
so it is "up to the minute". Rinse and repeat.

The format supports images, hyperlinks, a table of contents, an
index, a bibliography, appendicies, diagrams, audio, and video. 

The hard part is "reading the code" and trying to reverse engineer
what the core Clojure team wrote. This is code written by the best
in the business. Despite that and contrary to popular belief, reading
someone else's code is NOT easy to do.

Tim










-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Timothy Baldridge]

>> Clojure is being reworked into literate form already

Proof of this claim?




On Tue, May 6, 2014 at 7:32 PM, Gregg Reynolds  wrote:

> On Tue, May 6, 2014 at 2:22 PM, Tim Daly  wrote:
>
>> Gregg,
>>
>> > My original comment on litprog ("bad bad bad") was admittedly a little
>> > strong.  I think its bad for some things, fine for others.  And it's
>> > possible litprog conventions will evolve to address the problems some
>> of us
>> > see with using it for programming in the large etc.
>>
>> Could you explain what "some of the problems some of us see with using
>> it for programming in the large" might be? It is hard to refute
>> "bad bad bad" and other assertions without specific examples.
>>
>
> Hi Tim,
>
> I'm afraid it may take me a few days to find the time to respond
> properly.  In the meantime, aside from some of the responses in this
> thread, see
> http://stackoverflow.com/questions/2545136/is-literate-programming-dead .
>
> And here's a bit from Knuth (
> http://www-cs-faculty.stanford.edu/~uno/lp.html):
>
> "Literate programming  is a
> methodology that combines a programming language with a documentation
> language, thereby making programs more robust, more portable, more easily
> maintained, and arguably more fun to write than programs that are written
> only in a high-level language."
>
> "[T]hereby"???  This is an obvious non-sequitur.  To my knowledge neither
> Knuth nor anybody else has ever produced a shred of evidence in support of
> this kind of claim.   Probably because it is false on the face of it.  Note
> the implicit claim, that litprog is an "effective methodology" that, when
> followed, "thereby" results in all sorts of smooth buttery goodness
> (compare "effective procedure").  But litprog is a norm or style, not a
> methodology.  It provides no rules (methods) that all by themselves bestow
> excellence on your text.  You can write crappy literate programs.
>
> He continues: "The main idea is to treat a program as a piece of
> literature, addressed to human beings rather than to a computer."  *Rather*
> than to a computer?  I think not; nobody is interested in programs,
> literate or not, that computers do not understand.  Furthermore, program
> text is, has always been, and always will be a form of literary text, by
> definition.  Knuth's use of the term "literate programming" is a mere
> rhetorical trick since it (falsely) implies that programming that does not
> conform to his (very personal) notion of what counts as literate is ipso
> facto illiterate.
>
> Ross Williams (funnel web guy) (from http://www.literateprogramming.com/):
>
> "A traditional computer program consists of a text file containing program
> code. Scattered in amongst the program code are comments which describe the
> various parts of the code...In literate programming the emphasis is
> reversed. Instead of writing code containing documentation, the literate
> programmer writes documentation containing code."
>
> I consider this a major part of what "classic litprog" means, and I think
> it is preposterous, to be honest.  Just think of code and documentation as
> text and commentary.  One writes commentary about texts, not the other way
> around.
>
> Of course, this is not necessarily what everybody has in mind when they
> hear "literate programming".  In fact I gather it is not uncommon for
> people to use "literate programming" to refer to tools that merely support
> some kind of structured documentation syntax mixed in with code together
> with some kind of tools to support fancy typesetting.  On that view
> javadocs counts as literate programming.  But I think that's a confusing
> abuse of terminology, since that isn't what litprog originally meant.
>
> There's a lot more to be said about it, of course, but that'll have to do
> for now.
>
> And on the other hand, I'm entirely pragmatic about this stuff.  If
> something works and people use it, who am I to argue?  I just don't think
> it (classic litprog) works, at least not for certain important classes of
> problem (programming in the large, with distributed very heterogenous
> groups of programmers, etc.)  But there are lots of good docs tools that
> draw inspiration and techniques from classic litprog even if they
> themselves don't fit the profile precisley.
>
>
>> Axiom (1.2 million lines of lisp) is being rewritten into a literate
>> program. So far I can't think of a problem. Clojure is being reworked
>> into literate form already
>
>
> That's news to me.  Are you saying the core Clojure team is rewriting
> Clojure in *classic* litprog style?  That would flabber my gast, to put it
> mildly.
>
> -Gregg
>
>
> --
> 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
>

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Tue, May 6, 2014 at 2:22 PM, Tim Daly  wrote:

> Gregg,
>
> > My original comment on litprog ("bad bad bad") was admittedly a little
> > strong.  I think its bad for some things, fine for others.  And it's
> > possible litprog conventions will evolve to address the problems some of
> us
> > see with using it for programming in the large etc.
>
> Could you explain what "some of the problems some of us see with using
> it for programming in the large" might be? It is hard to refute
> "bad bad bad" and other assertions without specific examples.
>

Hi Tim,

I'm afraid it may take me a few days to find the time to respond properly.
In the meantime, aside from some of the responses in this thread, see
http://stackoverflow.com/questions/2545136/is-literate-programming-dead .

And here's a bit from Knuth (http://www-cs-faculty.stanford.edu/~uno/lp.html
):

"Literate programming  is a methodology
that combines a programming language with a documentation language, thereby
making programs more robust, more portable, more easily maintained, and
arguably more fun to write than programs that are written only in a
high-level language."

"[T]hereby"???  This is an obvious non-sequitur.  To my knowledge neither
Knuth nor anybody else has ever produced a shred of evidence in support of
this kind of claim.   Probably because it is false on the face of it.  Note
the implicit claim, that litprog is an "effective methodology" that, when
followed, "thereby" results in all sorts of smooth buttery goodness
(compare "effective procedure").  But litprog is a norm or style, not a
methodology.  It provides no rules (methods) that all by themselves bestow
excellence on your text.  You can write crappy literate programs.

He continues: "The main idea is to treat a program as a piece of
literature, addressed to human beings rather than to a computer."  *Rather*
than to a computer?  I think not; nobody is interested in programs,
literate or not, that computers do not understand.  Furthermore, program
text is, has always been, and always will be a form of literary text, by
definition.  Knuth's use of the term "literate programming" is a mere
rhetorical trick since it (falsely) implies that programming that does not
conform to his (very personal) notion of what counts as literate is ipso
facto illiterate.

Ross Williams (funnel web guy) (from http://www.literateprogramming.com/):

"A traditional computer program consists of a text file containing program
code. Scattered in amongst the program code are comments which describe the
various parts of the code...In literate programming the emphasis is
reversed. Instead of writing code containing documentation, the literate
programmer writes documentation containing code."

I consider this a major part of what "classic litprog" means, and I think
it is preposterous, to be honest.  Just think of code and documentation as
text and commentary.  One writes commentary about texts, not the other way
around.

Of course, this is not necessarily what everybody has in mind when they
hear "literate programming".  In fact I gather it is not uncommon for
people to use "literate programming" to refer to tools that merely support
some kind of structured documentation syntax mixed in with code together
with some kind of tools to support fancy typesetting.  On that view
javadocs counts as literate programming.  But I think that's a confusing
abuse of terminology, since that isn't what litprog originally meant.

There's a lot more to be said about it, of course, but that'll have to do
for now.

And on the other hand, I'm entirely pragmatic about this stuff.  If
something works and people use it, who am I to argue?  I just don't think
it (classic litprog) works, at least not for certain important classes of
problem (programming in the large, with distributed very heterogenous
groups of programmers, etc.)  But there are lots of good docs tools that
draw inspiration and techniques from classic litprog even if they
themselves don't fit the profile precisley.


> Axiom (1.2 million lines of lisp) is being rewritten into a literate
> program. So far I can't think of a problem. Clojure is being reworked
> into literate form already


That's news to me.  Are you saying the core Clojure team is rewriting
Clojure in *classic* litprog style?  That would flabber my gast, to put it
mildly.

-Gregg

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

On Tuesday, May 6, 2014 2:22:13 PM UTC-5, da...@axiom-developer.org wrote:
>
> Gregg, 
>
> > My original comment on litprog ("bad bad bad") was admittedly a little 
> > strong.  I think its bad for some things, fine for others.  And it's 
> > possible litprog conventions will evolve to address the problems some of 
> us 
> > see with using it for programming in the large etc. 
>
> Could you explain what "some of the problems some of us see with using 
> it for programming in the large" might be? It is hard to refute 
> "bad bad bad" and other assertions without specific examples. 
>
> Axiom (1.2 million lines of lisp) is being rewritten into a literate 
> program. So far I can't think of a problem. Clojure is being reworked 
> into literate form already and I can't see a problem other than trying 
> to understand and explain code I didn't write (reading code is hard). 
>
> The Clojure community isn't ready to make the leap into a literate 
> world. I understand that. But Clojure is still at the stage of writing 
> new code for new uses. There are few people who need to modify code 
> written by programmers who left the community. That's when the need 
> will arise for clearly communicating ideas to other humans. 
>
> The technical debt has not come due ... but it will. 
>
> Tim 
>

Previous posts in this and related threads make it clear that some people 
dislike literate programming as a general requirement.  I am one of them.  
At the same time, I think that literate programming is probably a Good 
Thing in certain contexts.  Some kinds of coding probably benefit from 
L.P.  At the very least L.P. a good thing in some contexts simply in that 
some people like it.  So I support it use in appropriate contexts--e.g. for 
projects carried out by people who like it, or for projects that would seem 
to derive special benefits from it.  I don't believe that L.P. is either 
necessary or sufficient for good documentation, and I would be dismayed if 
it were adopted as a general norm for Clojure.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Tim Daly]

> Adding complexity and weaving heapings of prose in amongst the code
> isn't going to make the developer that wrote the above rewrite it in a
> better way. You'll just end up with more bad documentation getting in
> the way of what the code actually does. Bad documentation is worse than
> no documentation. At least with no documentation, the code doesn't
> lie.

Bad documentation should have to leap the same hurdles as bad code.
Code review ought to be able to push back against bad documentation
just as easily as it screams at bad code. 

There is the famous "WTFs per minute" cartoon that can be applied to
documentation. Doing regular doc reviews might provide full employment
for English majors :-)

In fact, working on a WTF code review social process in Clojure might be
the most effective step toward better code and documentation overall.
Of course, this would have to be instituted by Rich and company since
they control the sources.

We could post code snippets (ref my prior post) which need explanation
and do a "community documentation upgrade" on the Clojure sources.

Tim

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Tim Daly]

Gregg,

> My original comment on litprog ("bad bad bad") was admittedly a little
> strong.  I think its bad for some things, fine for others.  And it's
> possible litprog conventions will evolve to address the problems some of us
> see with using it for programming in the large etc.

Could you explain what "some of the problems some of us see with using
it for programming in the large" might be? It is hard to refute 
"bad bad bad" and other assertions without specific examples.

Axiom (1.2 million lines of lisp) is being rewritten into a literate
program. So far I can't think of a problem. Clojure is being reworked
into literate form already and I can't see a problem other than trying
to understand and explain code I didn't write (reading code is hard).

The Clojure community isn't ready to make the leap into a literate
world. I understand that. But Clojure is still at the stage of writing
new code for new uses. There are few people who need to modify code
written by programmers who left the community. That's when the need
will arise for clearly communicating ideas to other humans.

The technical debt has not come due ... but it will. 

Tim





-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Sean Corfield]

On May 6, 2014, at 10:41 AM, Mark Engelberg  wrote:
> Sean, I think you missed the point of that example.

No, I was simply responding to Philip's assertion that the docstring was poorly 
written.

Sean Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/

"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)





signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: Proposing a new Clojure documentation system (in Clojure)

[u1204]

> Here's a concrete best-practices suggestion: follow the lead of Haskell and
> other functional languages in using x, y, z as generic type names, and x:xs
> (where 'xs' is plural of x) to indicate a list of xs; for seqs, maybe
> x::xs.  So I would rewrite your example to something like:  "[x y::ys] ->
> x::y::ys"

If you're citing Haskell's system as "best practice" perhaps we might
simply adopt their "literate" tools and techniques? 

Tim

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[John Gabriele]

On Tuesday, May 6, 2014 1:41:25 PM UTC-4, puzzler wrote:
>
> On Tue, May 6, 2014 at 9:56 AM, Sean Corfield 
> > wrote:
>
>>
>>
> Sean, I think you missed the point of that example.  The point was that 
> the docstring actually makes sense if it were written as:
>
> Returns a new seq where `x` is the first element and `seq` is the rest.
>
> Note how using standard markdown syntax helps distinguish the reference to 
> the `seq` arg and the more generic use of the term seq.  
>
> I think the Clojure community's lack of meaningful support for markdown in 
> docstrings is a glaring weakness that is fairly easy to rectify.  In the 
> meantime, I've begun using markdown syntax in my own docstrings, figuring 
> that someday the tools will eventually catch up and support it.
>
>
Using markdown in docstrings would be fantastic. This would enable tools 
like codox and autodoc to produce nice-looking html output from docstrings, 
instead of just docstring here output.

And the difference between the current Clojure docstrings and updated 
markdown-formatted docstrings is pretty minimal. Heck, I bet that 
markdown-i-fying the docstrings would even provide an easy on-ramp for a 
lot of folks (myself included) to get involved in the patch submission 
process...

Incidentally, I see that the [Rust](http://www.rust-lang.org/) folks use 
markdown-formatted docstrings. Have a look at some of [their API 
docs](http://static.rust-lang.org/doc/master/std/index.html). Very nice.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Tim Daly]

> Compare Emacs Lisp, for example, which uses semi-structure
> in the comments to drive many of its features.

Speaking of Emacs, there are (at least) two doc systems available,
the emacs "info" system and org-mode. Both of those evolved due to
a need for a better documentation system. 

The claim has been made that what exists is all we need since, if
there was MORE we need then a doc system would arise. Several dozen
have arisen and are in use.

Wouldn't a gif of Rich's Ant system running make the whole point
of the code perfectly obvious? Wouldn't it be even better if, when
you changed the code, the gif updated to reflect the new change?
We have Clojurescript and browsers have a canvas element.

Given that I only have a 640x480 terminal I guess ascii ants would
be ok :-)


-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Tim Daly]

> Less trivial things that I would like to be able to do: 
>  - transclude documentation from secondary files, so that the developer 
>of a piece of code sees a short piece of documentation, while users 
>of code can see something longer. 
>  - expand the documentation system as I see fit; i.e. the documentation 
>system should be designed to an abstraction, not an
>  implementation. 

   - include diagrams and pictures
   It is easy to show the red-black tree rebalance algorithm
 with a few pictures whereas the words are rather opaque. 
 Stacks and immutable copy algorithms are also easy in diagrams.
 You CAN do this with "ascii-art" but it IS the late 90s and some
 lucky few of us have 640x480 color terminals.

Tim



-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Mark Engelberg]

On Tue, May 6, 2014 at 9:56 AM, Sean Corfield  wrote:

> > Returns a new seq where x is the first element and seq is
> > the rest.
>
> Adding complexity and weaving heapings of prose in amongst the code isn't
> going to make the developer that wrote the above rewrite it in a better
> way. You'll just end up with more bad documentation getting in the way of
> what the code actually does. Bad documentation is worse than no
> documentation. At least with no documentation, the code doesn't lie.
>

Sean, I think you missed the point of that example.  The point was that the
docstring actually makes sense if it were written as:

Returns a new seq where `x` is the first element and `seq` is the rest.

Note how using standard markdown syntax helps distinguish the reference to
the `seq` arg and the more generic use of the term seq.

I think the Clojure community's lack of meaningful support for markdown in
docstrings is a glaring weakness that is fairly easy to rectify.  In the
meantime, I've begun using markdown syntax in my own docstrings, figuring
that someday the tools will eventually catch up and support it.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Sean Corfield]

On May 6, 2014, at 8:11 AM, Phillip Lord  wrote:
> I've used this example before; consider this unstructured string from
> `cons`.
> 
> Returns a new seq where x is the first element and seq is
> the rest.

Just because one (or several) of the clojure.core function docstrings are 
poorly written, doesn't mean Clojure's current documentation system is broken. 
This simply comes back to developers needing to write _better_ documentation, 
not _more_ documentation.

Adding complexity and weaving heapings of prose in amongst the code isn't going 
to make the developer that wrote the above rewrite it in a better way. You'll 
just end up with more bad documentation getting in the way of what the code 
actually does. Bad documentation is worse than no documentation. At least with 
no documentation, the code doesn't lie.

Sean Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/

"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)





signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Sat, May 3, 2014 at 3:46 PM, Val Waeselynck wrote:

> All right, I'll give it a try, here are some thoughts :
>
> I think it's too hard make precise requirements for advanced features in
> advance; I'd rather find a way to let usage drive us in the right
> direction. However, there are a few principles that we know will be wise to
> follow :
>
>- encouraging separation of concerns
>- avoiding duplication of logic
>
> And indeed as a programming language, Clojure follow these very well in
> many respects.
>
>   Applying these to the topic of documentation, I think it's a good idea
> to make the documentation system/process separate the concerns of writing
> quality code and making understandable. That seems to make a case towards
> documenting with tests/examples/schemas and against literate programming
> (was that your point, Gregg?)
>
Hi Val, sorry for getting back to you so late (was in the process of moving
to a new apartment the last few weeks so had intermittent web access).

My original comment on litprog ("bad bad bad") was admittedly a little
strong.  I think its bad for some things, fine for others.  And it's
possible litprog conventions will evolve to address the problems some of us
see with using it for programming in the large etc.

As for documenting with "tests/examples/schemas", I'm somewhere in that
general vicinity, but I think much more needs to be said about just what
that means, and what sort of norms should apply in each case.  See for
example https://github.com/mobileink/codegenres/wiki/Tests-as-Documentation(and
feel free to edit, it's just ideas now).

BTW, I discovered the links at
https://github.com/mobileink/codegenres/wikiwere broken; they're fixed
now.

- and maybe also against using types for documenting, but that's really my
> own personal feeling and I don't have any evidence for it.
>

Not sure what you mean; I consider type annotations (hints, whatever)
essential to good documentation.

-Gregg

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Tue, May 6, 2014 at 10:11 AM, Phillip Lord
wrote:

> Gregg Reynolds  writes:
> >> I think that the counter argument to that is that many other programming
> >> languages have a richer documentation system than Clojure, and many
> >> programmers use them.
> >>
> >> To be clear, Clojure's documentation system is an unstructured string,
> >> the arglists metadata and (arguably) the private metadata.
> >>
> >
> > I would add comment syntax.  Technically maybe not part of a doc
> "system",
> > but I have yet to meet a comment that doesn't count as documentation in
> > some sense.
>
>
> True, and, to some extent, it inherits the ";" vs ";;" comment
> distinction. But, again, there is not structure. This is an unstructured
> string also. Compare Emacs Lisp, for example, which uses semi-structure
> in the comments to drive many of its features.
>

I'm ok with some kind of structure for comments and docstrings, but I would
relegate it to an add-on, not part of the Clojure language definition.
We're effectively talking about adding a second syntax.  The original
poster (Val?) suggested using Clojure syntax for the documentation
language, but I'm not so sure about that yet; haven't thought about it
enough.  In principle I would think it would not be too terribly difficult
to hack a clojure parser to support a documentation mini-language for
comments and docstrings, effectively yielding a kind of clojure-docs
processor.

>> Trivial things that I would like to be able to do that I cannot do (in a
> >> way which will be reliably interpreted).
> >>
> >>  - Add hyperlinks
> >>  - Distinguish between symbols (or names of vars) and normal words.
> >>  - Distinguish between code (examples) and normal words
> >>  - Have access to basic "markdown" style typography.
> >>
> >
> > I'm undecided on these.  They would obviously be useful, but on the other
> > hand minimalism has its virtues.  In the base case of reading code with a
> > plaintext editor, I usually find embedded doco with lots of markup
> annoying
> > and an impediment to code reading.  I think I'm inclined to favor keeping
> > markup out of code but I'm keeping an open mind about it.
>
> I've used this example before; consider this unstructured string from
> `cons`.
>
> Returns a new seq where x is the first element and seq is
> the rest.
>
>
> So, cons returns a seq where x is the first element, and seq is the
> rest? Which means that cons returns the same (constantly x) for which
> (rest (constantly x)) could be said to equal (constantly x), as a
> infinite string of x's is the same as an infinite string of x's one
> shorter.
>

I would call that an example of sloppy documentation since it uses "seq" as
both a type name and a data name.  Support for structured strings can't
prevent that.

Here's a concrete best-practices suggestion: follow the lead of Haskell and
other functional languages in using x, y, z as generic type names, and x:xs
(where 'xs' is plural of x) to indicate a list of xs; for seqs, maybe
x::xs.  So I would rewrite your example to something like:  "[x y::ys] ->
x::y::ys"

Which leads to another suggestion: for documentation purposes, use "xs" (or
"ys", etc) instead of "coll", as the doc currently does.  For example, for
first,
instead of
first function

Usage: (first coll)

Returns the first item in the collection. Calls seq on its
argument. If coll is nil, returns nil.

We would have:

first x::xs -> x
first nil -> nil

To indicate that it calls seq on its arg, maybe something like:

first xs == first seq xs -> first x::xs -> x

where

seq xs -> x::xs  ;; by convention, 'xs' means 'collection of somethings'
and 'x::xs' means "sequence of somethings"
seq nil -> nil

I guess the point is that good, clear, concise, well-defined conventions
can solve a lot of problems before we even get to the issue of supporting
structured doc text.


> Although Clojure will take an infinite amount of time to test this for
> you.
>
>
>
>
> >
> > At the moment I'm leaning toward DITA for heavy-duty documentation, in
> part
> > because it would allow generation of manpages.  You can see an example at
> > leiningen-doc  - pdf output
> > examples are in doc/pdf.  It's mostly an outline at the moment, but if
> you
> > look at the driver file
> > ugbook.ditamap<
> https://github.com/mobileink/leiningen-doc/blob/master/ugbook.ditamap>and
> > the files in the ug directory you can get a quick idea of how it
> > works.  Once you get the hang of it you can quickly write doco in a
> > language specifically designed for tech documentation (and extend it if
> you
> > wish).
> >
> > That puts me in a small (infinitesimal?) minority, I reckon, but DITA is
> > evolving and growing, at least among professional tech writers.  An
> obvious
> > research topic is how Clojure and DITA might be made to play nice
> together.
>
> I was never a great fan of writing XML by

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Mars0i  writes:
>>  - Add hyperlinks 
>>  - Distinguish between symbols (or names of vars) and normal words. 
>>  - Distinguish between code (examples) and normal words 
>>  - Have access to basic "markdown" style typography. 
>>
>> Less trivial things that I would like to be able to do: 
>>  - transclude documentation from secondary files, so that the developer 
>>of a piece of code sees a short piece of documentation, while users 
>>of code can see something longer. 
>>  - expand the documentation system as I see fit; i.e. the documentation 
>>system should be designed to an abstraction, not an implementation. 
>>
>
> To me all of this seems reasonable, especially the first group of items.  
> None of the ones in the first group, at least, require immediate changes to 
> existing docstrings.  

They do, IF they are to be machine interpretable.

Emacs docstrings using `this' convention to identify other function or
variable names. I can use this convention in my clojure docstrings.
In emacs, the help system can make these hyperlinkable. Clojure
won't.

To have this work, we need a minimal standard. Nothing more complex, but
at least that.

Phil

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Gregg Reynolds  writes:
>> I think that the counter argument to that is that many other programming
>> languages have a richer documentation system than Clojure, and many
>> programmers use them.
>>
>> To be clear, Clojure's documentation system is an unstructured string,
>> the arglists metadata and (arguably) the private metadata.
>>
>
> I would add comment syntax.  Technically maybe not part of a doc "system",
> but I have yet to meet a comment that doesn't count as documentation in
> some sense.


True, and, to some extent, it inherits the ";" vs ";;" comment
distinction. But, again, there is not structure. This is an unstructured
string also. Compare Emacs Lisp, for example, which uses semi-structure
in the comments to drive many of its features.

>> Trivial things that I would like to be able to do that I cannot do (in a
>> way which will be reliably interpreted).
>>
>>  - Add hyperlinks
>>  - Distinguish between symbols (or names of vars) and normal words.
>>  - Distinguish between code (examples) and normal words
>>  - Have access to basic "markdown" style typography.
>>
>
> I'm undecided on these.  They would obviously be useful, but on the other
> hand minimalism has its virtues.  In the base case of reading code with a
> plaintext editor, I usually find embedded doco with lots of markup annoying
> and an impediment to code reading.  I think I'm inclined to favor keeping
> markup out of code but I'm keeping an open mind about it.

I've used this example before; consider this unstructured string from
`cons`.

Returns a new seq where x is the first element and seq is
the rest.


So, cons returns a seq where x is the first element, and seq is the
rest? Which means that cons returns the same (constantly x) for which
(rest (constantly x)) could be said to equal (constantly x), as a
infinite string of x's is the same as an infinite string of x's one
shorter.

Although Clojure will take an infinite amount of time to test this for
you.




>
> At the moment I'm leaning toward DITA for heavy-duty documentation, in part
> because it would allow generation of manpages.  You can see an example at
> leiningen-doc  - pdf output
> examples are in doc/pdf.  It's mostly an outline at the moment, but if you
> look at the driver file
> ugbook.ditamapand
> the files in the ug directory you can get a quick idea of how it
> works.  Once you get the hang of it you can quickly write doco in a
> language specifically designed for tech documentation (and extend it if you
> wish).
>
> That puts me in a small (infinitesimal?) minority, I reckon, but DITA is
> evolving and growing, at least among professional tech writers.  An obvious
> research topic is how Clojure and DITA might be made to play nice together.

I was never a great fan of writing XML by hand, to be honest (which is
what this appears to be). The first example that I looked at:

https://github.com/mobileink/leiningen-doc/blob/master/ug/classpath.dita

incidentally, appears to be ill-formed, having two "" tags.
XML is hard to write.


>> > If it were genuinely failing us in some important way, it would be
>> > changed.
>>
>> This is, I think, a variant of the no true Scotsman fallacy. You can
>> say, about any complaint about documentation system are wrong, because
>> if they were right, it would be changed. By definition I can produce no
>> counter examples.
>>
>
> Does that mean I win?  ;)

Yes, but only if you can prove that you are a true Scotsman.



> Actually I was thinking in terms of evolution rather than definition.
> Since version 1 of clojure lots of unmet needs have been identified and
> then met; the language has evolved in response to genuine needs (meaning:
> new stuff is actually used to do useful things).  Since that hasn't
> happened much (to my knowledge) with respect to doc features, I conclude
> that those features are at least minimally sufficient ("optimal" was a bad
> choice of words) to contribute to "survival".  I'm pretty sure Rich Hickey
> would reject any proposed changes to the language that did not meet a
> genuine unmet need, and the Clojure community is sufficiently active and
> competent and imaginative, that I'm strongly inclined to believe that, were
> the doc features genuinely deficient or inadequate in some way, the
> language would have evolved in some way to remedy the problem.


Many features added to Clojure come from other languages -- consider the
requirement (or otherwise) for keyword arguments. People feel the lack
of these features early on, when they try and port other code (or just
their mind) to a new language.

Documentation is about scalability; it only hits when you have a
reasonable amount of code (especially external libraries). It also hits
newcomers most.

So, perhaps, the time is now.

Phil

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To p

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

On Tuesday, May 6, 2014 9:39:47 AM UTC-5, Gregg Reynolds wrote:
>
> For what it's worth, I generally prefer manpages for API and language 
> documentation.  Very fast, with good search capabilities.  
>

I agree, but I suspect that this is a minority view.
 

> My main complaint about the Clojure doc ecosystem is that I can't do 
> something like $ man clj-doseq to see docs on doseq.
>

I have a script named 'cloman':

#!/bin/sh
echo "(doc $1)" | clojure | less

It's slow compared to real manpages, of course, because of Clojure's slow 
startup.  

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

On Tuesday, May 6, 2014 4:53:36 AM UTC-5, Phillip Lord wrote:
>
> Gregg Reynolds > writes: 
> > That sounds about right to me; communication (writing) skills, mainly. 
>  Of 
> > course, my degree is in the humanities, so I would say that.  Now I 
> think 
> > of computation as a new addition to the classic liberal arts. 
> > 
> > I'm beginning to think that the Clojure documentation system may be 
> > optimal.  Not "best possible", just optimal: does what it does (meets 
> > programmer needs) just well enough to survive.   
>
> I think that the counter argument to that is that many other programming 
> languages have a richer documentation system than Clojure, and many 
> programmers use them. 
>
> To be clear, Clojure's documentation system is an unstructured string, 
> the arglists metadata and (arguably) the private metadata. 
>
> Trivial things that I would like to be able to do that I cannot do (in a 
> way which will be reliably interpreted). 
>
>  - Add hyperlinks 
>  - Distinguish between symbols (or names of vars) and normal words. 
>  - Distinguish between code (examples) and normal words 
>  - Have access to basic "markdown" style typography. 
>
> Less trivial things that I would like to be able to do: 
>  - transclude documentation from secondary files, so that the developer 
>of a piece of code sees a short piece of documentation, while users 
>of code can see something longer. 
>  - expand the documentation system as I see fit; i.e. the documentation 
>system should be designed to an abstraction, not an implementation. 
>

To me all of this seems reasonable, especially the first group of items.  
None of the ones in the first group, at least, require immediate changes to 
existing docstrings.  In another post, Gregg Reynolds worries that 
implementing items in the first group would clutter up docstrings when read 
as raw text.  Maybe that's something to worry about, but a limited amount 
of well-known markup is easy to read raw.  Some people in recent threads 
are interested in more elaborate proposals.  That's when I start to wonder 
whether this is an attempt to replace a problem that's difficult to 
"program" (getting programmers to think in different, better ways about 
documentation) with one that's simpler (software tools or elaborate rules 
for documentation practice).

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Tue, May 6, 2014 at 4:53 AM, Phillip Lord
wrote:

> Gregg Reynolds  writes:
> > That sounds about right to me; communication (writing) skills, mainly.
>  Of
> > course, my degree is in the humanities, so I would say that.  Now I think
> > of computation as a new addition to the classic liberal arts.
> >
> > I'm beginning to think that the Clojure documentation system may be
> > optimal.  Not "best possible", just optimal: does what it does (meets
> > programmer needs) just well enough to survive.
>
> I think that the counter argument to that is that many other programming
> languages have a richer documentation system than Clojure, and many
> programmers use them.
>
> To be clear, Clojure's documentation system is an unstructured string,
> the arglists metadata and (arguably) the private metadata.
>

I would add comment syntax.  Technically maybe not part of a doc "system",
but I have yet to meet a comment that doesn't count as documentation in
some sense.

>
> Trivial things that I would like to be able to do that I cannot do (in a
> way which will be reliably interpreted).
>
>  - Add hyperlinks
>  - Distinguish between symbols (or names of vars) and normal words.
>  - Distinguish between code (examples) and normal words
>  - Have access to basic "markdown" style typography.
>

I'm undecided on these.  They would obviously be useful, but on the other
hand minimalism has its virtues.  In the base case of reading code with a
plaintext editor, I usually find embedded doco with lots of markup annoying
and an impediment to code reading.  I think I'm inclined to favor keeping
markup out of code but I'm keeping an open mind about it.


>
> Less trivial things that I would like to be able to do:
>  - transclude documentation from secondary files, so that the developer
>of a piece of code sees a short piece of documentation, while users
>of code can see something longer.
>  - expand the documentation system as I see fit; i.e. the documentation
>system should be designed to an abstraction, not an implementation.
>

All good; but personally I would want a way to do this kind of thing
without mixing a lot of "doc system" code in with the algorithm code.

For what it's worth, I generally prefer manpages for API and language
documentation.  Very fast, with good search capabilities.  My main
complaint about the Clojure doc ecosystem is that I can't do something like
$ man clj-doseq to see docs on doseq.

At the moment I'm leaning toward DITA for heavy-duty documentation, in part
because it would allow generation of manpages.  You can see an example at
leiningen-doc  - pdf output
examples are in doc/pdf.  It's mostly an outline at the moment, but if you
look at the driver file
ugbook.ditamapand
the files in the ug directory you can get a quick idea of how it
works.  Once you get the hang of it you can quickly write doco in a
language specifically designed for tech documentation (and extend it if you
wish).

That puts me in a small (infinitesimal?) minority, I reckon, but DITA is
evolving and growing, at least among professional tech writers.  An obvious
research topic is how Clojure and DITA might be made to play nice together.

More generally:  I'm inclined to think that the "native" doc support in
Clojure ("doc features" of the language itself) should be kept to a
minimum, and fancier stuff made available as add-ons.

Related: I think we need a better language for talking about
documentation.  Just consider the many ways people discover and access
documentation of various kinds, and their various reasons and purposes.
What "documentation" ought to look like (norms of content, organization,
functionality of the discovery/access system, etc.) may be different in
each case, so we need a concise language that allows us to clearly relate
needs to uses/purposes and so forth.  But currently our language is
relatively impoverished.  "Documentation" as commonly used covers just
about everything, so it is inevitable that major disagreements will arise
from people using the term with different ideas in mind.  Addressing this
need for clear articulation is part of the idea behind
codegenres.


> > If it were genuinely failing us in some important way, it would be
> > changed.
>
> This is, I think, a variant of the no true Scotsman fallacy. You can
> say, about any complaint about documentation system are wrong, because
> if they were right, it would be changed. By definition I can produce no
> counter examples.
>

Does that mean I win?  ;)

Actually I was thinking in terms of evolution rather than definition.
Since version 1 of clojure lots of unmet needs have been identified and
then met; the language has evolved in response to genuine needs (meaning:
new stuff is actually used to do useful things).  Since that hasn't
happened much (to my knowledge) with respect

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Gregg Reynolds  writes:
> That sounds about right to me; communication (writing) skills, mainly.  Of
> course, my degree is in the humanities, so I would say that.  Now I think
> of computation as a new addition to the classic liberal arts.
>
> I'm beginning to think that the Clojure documentation system may be
> optimal.  Not "best possible", just optimal: does what it does (meets
> programmer needs) just well enough to survive.  

I think that the counter argument to that is that many other programming
languages have a richer documentation system than Clojure, and many
programmers use them.

To be clear, Clojure's documentation system is an unstructured string,
the arglists metadata and (arguably) the private metadata.

Trivial things that I would like to be able to do that I cannot do (in a
way which will be reliably interpreted).

 - Add hyperlinks
 - Distinguish between symbols (or names of vars) and normal words.
 - Distinguish between code (examples) and normal words
 - Have access to basic "markdown" style typography.

Less trivial things that I would like to be able to do:
 - transclude documentation from secondary files, so that the developer
   of a piece of code sees a short piece of documentation, while users
   of code can see something longer.
 - expand the documentation system as I see fit; i.e. the documentation
   system should be designed to an abstraction, not an implementation.


> If it were genuinely failing us in some important way, it would be
> changed.

This is, I think, a variant of the no true Scotsman fallacy. You can
say, about any complaint about documentation system are wrong, because
if they were right, it would be changed. By definition I can produce no
counter examples.

Phil

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Mon, May 5, 2014 at 9:32 AM, Mars0i  wrote:
...

> the end, there are no fixed rules.  Just figure out what your readers or
> students need, however you do it.
>
> That's exactly what good documentation involves: Figuring out what other
> programmers will need when they read your code.  (And figuring out how to
> communicate that.)
>
> I think that some of the ideas that people have been proposing in these
> threads are good.  There are some things that it's good to do routinely,
> even if you aren't thinking much about the intended audience.  And the
> right tools and conventions can help convey information more clearly.
> Obviously, a lot of the discussion here is already focused on thinking
> about needs readers of code, so in a sense I'm not saying anything new.
>
> Still, thinking about programmers I've worked with in the past, a part of
> me wonders whether part of what's needed is not programming (with code or
> rules), but also a focus on cultivation of a set of skills that are not
> *programming* skills per se.  Good tools or rules will only get us so far.
>

That sounds about right to me; communication (writing) skills, mainly.  Of
course, my degree is in the humanities, so I would say that.  Now I think
of computation as a new addition to the classic liberal arts.

I'm beginning to think that the Clojure documentation system may be
optimal.  Not "best possible", just optimal: does what it does (meets
programmer needs) just well enough to survive.  If it were genuinely
failing us in some important way, it would be changed.

-Gregg

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

(There are now three recent threads on documentation in the Clojure Google 
group*.  *The other threads are "Code Genres" and "Deep Thinking".  It was 
actually *da...@axiom-developer.org's May* 4 post in "Deep Thinking" that 
stimulated these remarks; I posted in this thread only because 
it has "documentation" in the title, so the intent is clearer, but if 
you're new to these discussions, you should read the other threads as well.)

A thought crystallized out of my slight discomfort with some of the remarks 
on documentation in this group lately.  I kept thinking "I have written 
good documentation in the past (sometimes), when other programmers with 
whom I worked didn't.  And we didn't have any special tools.  Just text 
editors.   Why do I need special tools for documentation?"  (Of course I do 
think special tools for documentation can be a good thing. sometimes, but I 
kept having this thought all the same.)

We're programmers, so it's natural to try to problems by programming.  In 
trying to improve documentation this could involve programming in the usual 
sense (writing code), or programming the programmers (creating informal or 
more formal standards for documentation).

I used to work as a professional programmer, but now I'm a professor in a 
humanities discipline.  (I do Clojure programming as part of some of my 
research projects.)  I think a lot about writing clearly and about 
teaching.  For both, there are are methods, guidelines, rules of thumb, 
things to try out, etc., but the most important thing is to try to think 
through what your intended audience needs in order to understand.  And in 
the end, there are no fixed rules.  Just figure out what your readers or 
students need, however you do it.

That's exactly what good documentation involves: Figuring out what other 
programmers will need when they read your code.  (And figuring out how to 
communicate that.)

I think that some of the ideas that people have been proposing in these 
threads are good.  There are some things that it's good to do routinely, 
even if you aren't thinking much about the intended audience.  And the 
right tools and conventions can help convey information more clearly.  
Obviously, a lot of the discussion here is already focused on thinking 
about needs readers of code, so in a sense I'm not saying anything new.

Still, thinking about programmers I've worked with in the past, a part of 
me wonders whether part of what's needed is not programming (with code or 
rules), but also a focus on cultivation of a set of skills that are not 
*programming* skills per se.  Good tools or rules will only get us so far.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

All right, I'll give it a try, here are some thoughts :

I think it's too hard make precise requirements for advanced features in 
advance; I'd rather find a way to let usage drive us in the right 
direction. However, there are a few principles that we know will be wise to 
follow :

   - encouraging separation of concerns
   - avoiding duplication of logic

And indeed as a programming language, Clojure follow these very well in 
many respects. 

  Applying these to the topic of documentation, I think it's a good idea to 
make the documentation system/process separate the concerns of writing 
quality code and making understandable. That seems to make a case towards 
documenting with tests/examples/schemas and against literate programming 
(was that your point, Gregg?) - and maybe also against using types for 
documenting, but that's really my own personal feeling and I don't have any 
evidence for it.

  Avoiding duplication of logic seems to encourage the overlapping of tests 
and documentation examples in code, so something close to what 
lein-midje-doc currently offers.

  Is that OK for everyone?
Le vendredi 2 mai 2014 16:16:24 UTC+2, Gregg Reynolds a écrit :
>
> On Fri, May 2, 2014 at 4:00 AM, Val Waeselynck 
> 
> > wrote:
>
>>
>> That is NOT what I said. Please go back and read my response more 
>>> carefully. 
>>>
>>
>> Apologies, guess I disagree only with Gregg on that point then.
>>
>
> I guess this illustrates a point that is usually overlooked: no matter how 
> good your documentation is, somebody will always misread it.  Which gets 
> back to the point I was trying to make: the ultimate source of 
> authoritative information about what the code does is the code itself.  It 
> does not follow that the names used in the code are reliable guides to what 
> the code means.  Consider the following (mangled from 
> http://en.wikibooks.org/wiki/Clojure_Programming/Examples/Lazy_Fibonacci):
>
> (def factorial 
>   ((fn rfact [a b] 
>  (lazy-seq (cons a (rfact b (+ a b)
>0 1))
>
>
> Obviously not a factorial function; to know what it is, you have to read 
> the code, which expresses an algorithm (in this case fibonacci).  Something 
> this extreme probably doesn't happen very often, but something very like it 
> happens all the time.  Yesterday I was working through some Java code 
> called "fooReader".  The docstring said it inherited from XMLReader.  It 
> did not, rather it inherited from XMLFilter.  Which in turn inherits from 
> AbstractWriter.  So what is it, a Reader, Filter, or Writer?  The only way 
> to find out is to read the code - that is, the algorithm, not just the 
> names.   (This code was documented, by the way.)  In my experience clashes 
> between the natural language semantics of function and var names on the one 
> had, and the jobs they actually do on the other, is pervasive, and I see 
> little chance that this will ever change.  Not because programmers are dumb 
> but because coming up with expressive and accurate names is hard and time 
> consuming.
>
> Which leads to a larger point: a genuine improvement in the Clojure 
> documentation situation requires (IMHO) some Deep Thinking about the nature 
> of code, the relation between code (text) and algorithm, natural language 
> text, expressivity, programmer practices, etc.  In other words, we should 
> follow Rich Hickey's example - I take it that Clojure itself emerged from 
> some Deep Thinking about the nature of computation, programming language 
> design, etc.
>
> -Gregg
>
>
>
>

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Fri, May 2, 2014 at 4:00 AM, Val Waeselynck wrote:

>
> That is NOT what I said. Please go back and read my response more
>> carefully.
>>
>
> Apologies, guess I disagree only with Gregg on that point then.
>

I guess this illustrates a point that is usually overlooked: no matter how
good your documentation is, somebody will always misread it.  Which gets
back to the point I was trying to make: the ultimate source of
authoritative information about what the code does is the code itself.  It
does not follow that the names used in the code are reliable guides to what
the code means.  Consider the following (mangled from
http://en.wikibooks.org/wiki/Clojure_Programming/Examples/Lazy_Fibonacci):

(def factorial
  ((fn rfact [a b]
 (lazy-seq (cons a (rfact b (+ a b)
   0 1))


Obviously not a factorial function; to know what it is, you have to read
the code, which expresses an algorithm (in this case fibonacci).  Something
this extreme probably doesn't happen very often, but something very like it
happens all the time.  Yesterday I was working through some Java code
called "fooReader".  The docstring said it inherited from XMLReader.  It
did not, rather it inherited from XMLFilter.  Which in turn inherits from
AbstractWriter.  So what is it, a Reader, Filter, or Writer?  The only way
to find out is to read the code - that is, the algorithm, not just the
names.   (This code was documented, by the way.)  In my experience clashes
between the natural language semantics of function and var names on the one
had, and the jobs they actually do on the other, is pervasive, and I see
little chance that this will ever change.  Not because programmers are dumb
but because coming up with expressive and accurate names is hard and time
consuming.

Which leads to a larger point: a genuine improvement in the Clojure
documentation situation requires (IMHO) some Deep Thinking about the nature
of code, the relation between code (text) and algorithm, natural language
text, expressivity, programmer practices, etc.  In other words, we should
follow Rich Hickey's example - I take it that Clojure itself emerged from
some Deep Thinking about the nature of computation, programming language
design, etc.

-Gregg

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Thu, May 1, 2014 at 9:49 PM, Sean Corfield  wrote:

> On Apr 30, 2014, at 4:08 PM, Val Waeselynck  wrote:
> >   As for what Gregg and Sean objected - that Clojure code is
> self-sufficient as documenting itself - I have to simply disagree.
>
> That is NOT what I said. Please go back and read my response more
> carefully.


Not what I said either.  Where did "self-sufficient" come from?

-Gregg

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

> That is NOT what I said. Please go back and read my response more 
> carefully. 
>

Apologies, guess I disagree only with Gregg on that point then.
 

> >   Anyway, I think speculating about the necessity of such a 
> documentation system is not the best thing to do - I suggest we give it a 
> try, and then everyone can decide for themselves if it's useful. After all, 
> it's in Clojure, so this should not take too long, right ? ;) 
>
> Go ahead and build something and see if people like it. That's probably a 
> better approach than trying to discuss it anyway. 
>

We'll do.
 

> Sean Corfield -- (904) 302-SEAN 
> An Architect's View -- http://corfield.org/ 
>
> "Perfection is the enemy of the good." 
> -- Gustave Flaubert, French realist novelist (1821-1880) 
>
(By the way, that's actually from Montesquieu (Liberalist ,1689-1755), in 
*Cahiers*. I'd rather translate it "Better is the deadly enemy of good".)
 

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Sean Corfield]

On Apr 30, 2014, at 4:08 PM, Val Waeselynck  wrote:
>   As for what Gregg and Sean objected - that Clojure code is self-sufficient 
> as documenting itself - I have to simply disagree.

That is NOT what I said. Please go back and read my response more carefully.

>   Anyway, I think speculating about the necessity of such a documentation 
> system is not the best thing to do - I suggest we give it a try, and then 
> everyone can decide for themselves if it's useful. After all, it's in 
> Clojure, so this should not take too long, right ? ;)

Go ahead and build something and see if people like it. That's probably a 
better approach than trying to discuss it anyway.

Sean Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/

"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)





signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: Proposing a new Clojure documentation system (in Clojure)

[John Gabriele]

On Wednesday, April 30, 2014 5:48:17 PM UTC-4, Sean Corfield wrote:
>
>
> For a project that has its auxiliary documentation on a Github wiki, you 
> don't even need to git clone & edit the repo: you can simply click Edit 
> Page. That's about a low a barrier to entry as there can be and we still 
> don't see enough contribution to documentation. 
>
>  
Via the wonders of github, this even works if the docs in question are just 
simple .md files. Once you're logged into github, forking, editing, & 
submitting a PR is only a couple of clicks as well. Contributors can edit 
the doc/*.md file(s) right there without ever touching `git` or leaving the 
browser.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[guns]

On Thu  1 May 2014 at 09:05:29AM -0700, Mars0i wrote:

> 1. Functions have complex intended type signatures: Functions can have
> multiple parameter sequences, because of optional arguments with &,
> and because of complex arguments such as maps.

Schema expresses these scenarios quite well, as does core.typed AFAIK.

> 2. Many functions with a base intended use are also intended to have
> more general uses. This is particularly common for functions that are
> part of the Clojure language itself.

Constraining inputs to those that satisfy protocols and interfaces goes
a long way, and provides considerable flexibility, while still providing
meaningful constraints.

Have a function that uses `slurp` or `spit` on a parameter? Declare that
the parameter satisfies clojure.java.io/Coercions.

Have a function that expects any kind of map-like object that supports
`get`? Declare that it must satisfy clojure.lang.Associative.

And so on. Together with Java type hierarchies, I have found it quite
easy to declare polymorphic function signatures using Schema.

guns


pgpbQdkXAUa7G.pgp
Description: PGP signature

Re: Proposing a new Clojure documentation system (in Clojure)

[Ambrose Bonnaire-Sergeant]

(Author of core.typed) Typed Clojure's function syntax generally won't get
in your way if you're trying to jot down a type signature. It can handle
multiple arities, polymorphism, keyword arguments, rest arguments and more.

The whole point of Typed Clojure is to model how programmers use Clojure.
eg. the semantics for
first.
We're actively expanding what can be expressed with types.

Thanks,
Ambrose

On Fri, May 2, 2014 at 12:05 AM, Mars0i  wrote:

>
>
> On Wednesday, April 30, 2014 1:03:24 PM UTC-5, Gregg Reynolds wrote:
>
>> The one thing that I think would be genuinely useful and developer
>> friendly with respect to Clojure is a means of making type signatures
>> explicit.  Clojure may be dynamically typed, but everything has an intended
>> type, and I would like to see it.  I'm thinking of something along the way
>> Haskell and other languages express type sigs.  The paradigmatic example is
>> factorial (or fibonacci).  So given a factorial function "fact" I want to
>> be able to write something like (type-sig fact) and get something like "Int
>> -> Int"
>>
>
> I think this is a great idea.  A type-sig functions is a nice idea, but
> one can do this now, by adding to docstrings.  I am going to think about
> adding something like this to the docstrings for my own code.  Sean made an
> interesting point about core.typed, but I'm not sure whether it gets in the
> way of documenting intended signatures.  Jony suggested Prismatic/schema.
> That looks like a useful tool, but it wasn't clear to me, without
> installing it an playing with it for a bit, whether it generates nice
> signatures as documentation that can be called up in the REPL, IDEs, etc.
> (It also seems to be Clojurescript-specific at this point.)
>
> It seems as if a syntax for intended type signatures is obviously not
> entirely simple, for at least two reasons.
>
> 1. Functions have complex intended type signatures:  Functions can have
> multiple parameter sequences, because of optional arguments with &, and
> because of complex arguments such as maps.
>
> 2. Many functions with a base intended use are also intended to have more
> general uses.  This is particularly common for functions that are part of
> the Clojure language itself.  (What sort of intended type signatures should
> the function seq have, given that the docstring for empty? says: "Please
> use the idiom (seq x) rather than (not (empty? x))" ?)  On the other hand
> I'm sure that most functions defined outside of a general-purpose tool
> collection (such as Clojure itself) are intended *only* for very specific
> uses.
>
> Perhaps a syntax of such "intended-type-signatures" would be worth
> discussion in another thread.  The typed FP tradition embodied in Haskell
> may have already worked out solutions to the first set of complications,
> but not the second issue.
>
>  --
> 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 unsubscribe from this group and stop receiving emails from it, send an
> email to clojure+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

On Wednesday, April 30, 2014 1:03:24 PM UTC-5, Gregg Reynolds wrote:

> The one thing that I think would be genuinely useful and developer 
> friendly with respect to Clojure is a means of making type signatures 
> explicit.  Clojure may be dynamically typed, but everything has an intended 
> type, and I would like to see it.  I'm thinking of something along the way 
> Haskell and other languages express type sigs.  The paradigmatic example is 
> factorial (or fibonacci).  So given a factorial function "fact" I want to 
> be able to write something like (type-sig fact) and get something like "Int 
> -> Int"
>

I think this is a great idea.  A type-sig functions is a nice idea, but one 
can do this now, by adding to docstrings.  I am going to think about adding 
something like this to the docstrings for my own code.  Sean made an 
interesting point about core.typed, but I'm not sure whether it gets in the 
way of documenting intended signatures.  Jony suggested Prismatic/schema.  
That looks like a useful tool, but it wasn't clear to me, without 
installing it an playing with it for a bit, whether it generates nice 
signatures as documentation that can be called up in the REPL, IDEs, etc.  
(It also seems to be Clojurescript-specific at this point.)

It seems as if a syntax for intended type signatures is obviously not 
entirely simple, for at least two reasons. 

1. Functions have complex intended type signatures:  Functions can have 
multiple parameter sequences, because of optional arguments with &, and 
because of complex arguments such as maps.   

2. Many functions with a base intended use are also intended to have more 
general uses.  This is particularly common for functions that are part of 
the Clojure language itself.  (What sort of intended type signatures should 
the function seq have, given that the docstring for empty? says: "Please 
use the idiom (seq x) rather than (not (empty? x))" ?)  On the other hand 
I'm sure that most functions defined outside of a general-purpose tool 
collection (such as Clojure itself) are intended *only* for very specific 
uses.  

Perhaps a syntax of such "intended-type-signatures" would be worth 
discussion in another thread.  The typed FP tradition embodied in Haskell 
may have already worked out solutions to the first set of complications, 
but not the second issue.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Sean Corfield  writes:

> Short, clear docstrings and well-structured code with well-named
> symbols short provide enough information for maintenance.

But, sadly, not enough documentation for use. The state of Clojure
survey brings up complaints about the documentation of clojure.core
every year.

Partly this because the documentation is not very good -- I still use
Clojuredocs regularly, even though it's rather rusting away being on
1.3.  I rarely read the documentation, just skip to the examples.

But, partly, it's because the documentation format is just too simple.
Javadoc, for example, is far better. And is Javadoc literate
programming? If it is, then the idea that "no one uses literate
programming" is wrong, if it is not, then literate programming is
irrelevant.

Even some simple documentation standards for Clojure, distinguishing
parameters, functions and so on would be a step forward. And it needs to
go into clojure.core so that tools support it.

Phil


-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

Sorry I have been late to react to all this, since I'm the one who started 
it all.

First, *as a side note* : I have nothing against docstrings. I acknowledge 
their benefits, I think we should keep using them and I enjoy them every 
day like all of you. My point was just that they were not enough for all 
documentation, I probably wasn't very clear on that. Stop shooting :)

@Fergal : thanks for such a great tour. It seems I have a lot of catching 
up to do before I have a keen understanding of the currently existing 
options. Nevertheless, I'll try to make a relevant contribution to the 
discussion.

  Given some of the answers, I'd like as a precaution emphasize the fact 
that I'm not trying to "sell" you a documentation system nor impose a 
dogma. My intent in proposing these approximative features was that, 
through some refining, some proposing and some discarding, the discussion 
will converge to a precise idea of what we want for documentation and how 
we should do it.

  
  As for what Gregg and Sean objected - that Clojure code is 
self-sufficient as documenting itself - I have to simply disagree. I do not 
want to have a theoretical discussion on this, because I think it's 
pointless; it is an empirical observation to me that foreign Clojure code 
tends to be difficult to understand. I have felt that pain, many times and 
despite all my stubbornness, which is why I finally posted here. I I'm the 
only one, please tell me.

   I think it is very important to raise the awareness of all Clojure 
programmers, especially library authors, that there is a significant 
asymmetry of information here : namely, it's easier than ever to go from 
intent to code, and much harder to go the way back. I see it at work when I 
edit my own code too : the programs seem to organize themselves naturally 
as I write them, sometimes in such a mechanical way that I have 
difficulties finding names for the abstractions I program, and I do get a 
crystal-clear understanding of them; but I'm quite sure that it would be 
very obscure to me if I had not witnessed the process. Try to make a Ring 
middleware or a monad self-explanatory with just code and a schema.

  Undoubtedly, library authors will feel this duty of documentation like a 
hinderance. I believe this is a necessary tradeoff to make. Besides, if 
you're code changes so fast that documentation quickly becomes obsolete, 
isn't that a sign that your API isn't ready to be exported?

  
  Anyway, I think speculating about the necessity of such a documentation 
system is not the best thing to do - I suggest we give it a try, and then 
everyone can decide for themselves if it's useful. After all, it's in 
Clojure, so this should not take too long, right ? ;)
 
 samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit :
>
> Hello to all,
>
> *Short version :* I think Clojure needs a documentation system in 
> Clojure, I would like to know if some efforts exist in that direction, and 
> I am willing to create it / contribute to it.
>
> *Long version :*
>
> I've been thinking for a while that the Clojure community could benefit a 
> lot from a more sophisticated and ergonomic documentation system. 
>
> I have seen some existing plugins like lein-sphinx, but I think it would 
> be really good to have documentation that would be written in Clojure, for 
> the following reasons :
>
>- we're all very fond of Clojure data structures and their syntax. (I 
>don't know about you, but I find that even HTML looks better in 
> Clojurethan in HTML). Plus, Clojure 
> programmers already know how to edit them.
>- (better reason) The facts that Vars are first-class citizens and 
>that symbols can be referred explicitly with hardly any ceremony (macros) 
>are a exceptional opportunity to make smart and highly-structured 
>documentation very easily.
>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
> hoc*documentation functionality on top of it to suit their own particular 
> needs.
>
> I haven't found anything of the like yet, and if it exists, I would be 
> grateful if someone would redirect me to it.
>
> Here are *my thoughts on this :*
>
>1. Clojure doc-strings, although they are quite handy as reminders and 
>for doc-indexation, are *too raw a content*. Even when they are done 
>right, they tend to be cumbersome, and it's too bad to have such concise 
>code drown in the middle of so much documentation. What's more, I believe 
>that when programmers program a function (or anything), they tend to think 
>more about the implementation than the (uninformed) usage, so they have 
>little incentive to make it right.
>2. Building on 1. having a system where documentation and programs 
>live in separate files, in the same way as tests, would enforce a healthy 
>separation of concerns. Importantly, it would make life much easier on the 
>Version Control perspect

Re: Proposing a new Clojure documentation system (in Clojure)

[Sean Corfield]

On Apr 29, 2014, at 9:42 PM, Atamert Ölçgen  wrote:
> Since I don't use emacs, I would probably have found the former easier.

I don't think Emacs has anything to do with this, even tho' Phil used the 
example of org-mode etc. I agree that if working on the code - and keeping the 
copious documentation in sync - requires anything more than a simple text 
editor, it's going to create obstacles to the workflow.

For a project that has its auxiliary documentation on a Github wiki, you don't 
even need to git clone & edit the repo: you can simply click Edit Page. That's 
about a low a barrier to entry as there can be and we still don't see enough 
contribution to documentation.

Sean Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/

"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)





signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: Proposing a new Clojure documentation system (in Clojure)

[Sean Corfield]

On Apr 30, 2014, at 11:03 AM, Gregg Reynolds  wrote:
> Controversial:  literate programming is a bad, bad, bad idea.  There is a 
> reason it has never caught on.

I was going to stay out of this discussion but... I agree with Gregg here. All 
that prose just gets in the way and inhibits the largest portion of software 
development: maintenance. Sure, it's great in theory to have all that 
documentation right there when you're first learning a code base, but then it 
just gets in the way - and you're still not guaranteed that any maintenance 
that is done will keep the (extensive) documentation up to date. Most 
programmers just don't work well with prose - neither at reading it nor writing 
it.

I think Clojure's docstrings are a great compromise: something built into the 
language for each "file" (namespace) and each var and function. I wish 
docstrings could be added to some other constructs (defmethod, in particular, 
but also the "pure Java" definterface / defrecord / deftype stuff). Short, 
clear docstrings and well-structured code with well-named symbols short provide 
enough information for maintenance. Rationale, concepts and extensive examples 
belong outside the code for that "first use" scenario, IMO.

> The one thing that I think would be genuinely useful and developer friendly 
> with respect to Clojure is a means of making type signatures explicit.  
> Clojure may be dynamically typed, but everything has an intended type, and I 
> would like to see it.  I'm thinking of something along the way Haskell and 
> other languages express type sigs.  The paradigmatic example is factorial (or 
> fibonacci).  So given a factorial function "fact" I want to be able to write 
> something like (type-sig fact) and get something like "Int -> Int".

Having used core.typed at work, I'll posit that type inference on most Clojure 
code won't actually tell you a lot. The inferred types would be pretty general. 
Even when adding annotations (for core.typed's analysis), it's sometimes 
surprisingly hard to crank down the type signatures and still get everything to 
type check: you often need either much more general types than you might wish 
for or you end up with complex union types, partly due to nil-punning and 
Clojure's view of truthy / falsey.

Sean Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/

"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)





signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: Proposing a new Clojure documentation system (in Clojure)

[Jony Hudson]

On Wednesday, 30 April 2014 19:03:24 UTC+1, Gregg Reynolds wrote:

>
> The one thing that I think would be genuinely useful and developer 
> friendly with respect to Clojure is a means of making type signatures 
> explicit.  Clojure may be dynamically typed, but everything has an intended 
> type, and I would like to see it.  I'm thinking of something along the way 
> Haskell and other languages express type sigs.  The paradigmatic example is 
> factorial (or fibonacci).  So given a factorial function "fact" I want to 
> be able to write something like (type-sig fact) and get something like "Int 
> -> Int".
>

(I think someone might have mentioned it above, but it doesn't hurt to 
repeat) you might like schema https://github.com/Prismatic/schema/ .


Jony

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Gregg Reynolds]

On Tue, Apr 29, 2014 at 7:44 PM, Phil Hagelberg  wrote:

> On Saturday, April 26, 2014 9:21:26 PM UTC-7, Mars0i wrote:
> > I like the general idea of the Valentin's proposal, but I don't
> > understand every bit of it.  It sounds complicated.  Personally, I'd
> > rather see something that's relatively simple, and good enough, than
> > something that's perfect but unwieldy.  If it's too difficult, people
> > won't use it, or they'll waste time, or feel that the Clojure
> > community expects them to spend too much time on something that
> > detracts from what's important.
>
> Double-inc[1] on this. Clojure needs people who care about documentation
> far more than it needs another documentation system. Don't try to apply a
> technical solution to a social problem.
>


Double-dog dinc.  Having followed this thread I hazard a few reminders of
the obvious.  Code *is* documentation.  Programmers don't like to write
"documentation" - it's hard enough to write good code, and then you want me
to translate my code into clear simple concise English?  (Are you nuts?
Learn to read code!)  Writing good documentation and writing good code are
distinct skills that are very rarely found in a single person.  Good
documentation is expensive.  "Good" means "good enough".

Less obvious: there are at least two distinct notions of documentation in
play.  One is the code: self-documenting documentation.  The other is
arguably meta-documentation: English (usually) prose *about* the code -
which means, about the self-documenting documentation.

Controversial:  literate programming is a bad, bad, bad idea.  There is a
reason it has never caught on.  Ever try to hack Tex?  Did Knuth's
"literate" code help?  Maybe; but people routinely tackle systems that are
just as complex without the added burden of tangle and weave, etc.  Many
years ago I had to do maintenance work on a banking system written entirely
in S/370 assembler.  It was a pain, but it was doable.  Literate
programming would have made it far worse, in my opinion.  Would it be
easier to hack TeX if it had been written without the lit prog cruft?  In
my view the answer is (probably) yes.  (Note that, until relatively
recently, (XeTeX and LuaTex) there was almost no work that built on TeX to
make new stuff - which is what Knuth had hoped for.)  But the more critical
point is that TeX was (mostly) a one-man show.  Literate programming fine
for that, but is utterly, irredeemably, terminally unsuitable for the sorts
of projects that work in the open source world - lots of different people,
scratching lots of different itches, with lots of different opinions about
the Way the World Ought To Work.  I can see no reason to think that
"literate code" is in any way immune to the problems that inevitably
afflict any successful software project - bitrot, feature creep,
over-engineering, under-specification, gradual divergence between
descriptions of the system and what it actually does, pressure to just make
the damn thing work (as opposed to "doing it right"), etc. etc. etc.  My
heart sinks whenever I see a project that looks good but is implemented in
"literate" programming.  If I really like it and want to bang on it, the
first thing I will do is terminate the literate stuff with extreme
prejudice - give me the code, please, and the minimal amount of local
commenting.  I'll read the "literate" docs, but will never code the stuff.

The one thing that I think would be genuinely useful and developer friendly
with respect to Clojure is a means of making type signatures explicit.
Clojure may be dynamically typed, but everything has an intended type, and
I would like to see it.  I'm thinking of something along the way Haskell
and other languages express type sigs.  The paradigmatic example is
factorial (or fibonacci).  So given a factorial function "fact" I want to
be able to write something like (type-sig fact) and get something like "Int
-> Int".

-Gregg

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Sean Johnson]

Valentin, et al,

I'm a little late to the thread here, but I'm the author of lein-sphinx 
which you mentioned in your (well thought out) post so I thought I'd weigh 
in here.

I agree with a lot of what you wrote in your proposal, and for many 
projects (not all of them, but many) there is an important role for 
documentation that is separate from code. Maybe there needs to be a chapter 
length explanation of system X that your library is intending to interact 
with system X before the code (and docstrings) even make any sense to 
someone new to the codebase. You're going to put all that content in the 
code in doc strings? No. Maybe you put it in Markdown and let GitHub render 
it, but even with GH's proprietary extensions of MD, it's limited when 
compared to something like Sphinx and reStructured Text.

So that's where something like lein-sphinx comes in, and I built that 
simply as a necessary evil. I'm not a big Python guy, or a fan of 
reStructured Text or Sphinx, but I felt there was nothing equivalent for 
building up real substantial docs in Clojure.

I have some specific thoughts on your proposal are below:

I've been thinking for a while that the Clojure community could benefit a 
> lot from a more sophisticated and ergonomic documentation system. 
>

I would have said "usable", but I love your choice of "ergonomic" here to 
describe software. I think "usability" is a bit of an overused word that's 
lost some of its power. I'm going to steal this and start using 
"ergonomic". Thanks!

I have seen some existing plugins like lein-sphinx, but I think it would be 
> really good to have documentation that would be written in Clojure, for the 
> following reasons :
>
>- we're all very fond of Clojure data structures and their syntax. (I 
>don't know about you, but I find that even HTML looks better in 
> Clojurethan in HTML). Plus, Clojure 
> programmers already know how to edit them.
>
> hmmm... I like that we could use Clojure syntax to describe Clojure syntax 
and Clojure data structures. I'm not so sure I'm so fond of Clojure syntax 
that I want to use it for sentences. And I don't think HTML looks better in 
Clojure, there's a lot of really nasty HTML out there. Nasty HTML looks 
nasty in Clojure too, and nice HTML looks better in HTML than in Clojure. 

>
>- (better reason) The facts that Vars are first-class citizens and 
>that symbols can be referred explicitly with hardly any ceremony (macros) 
>are a exceptional opportunity to make smart and highly-structured 
>documentation very easily.
>
> mmk. 

>
>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
> hoc*documentation functionality on top of it to suit their own particular 
> needs.
>
> I like this reason.
 

> I haven't found anything of the like yet, and if it exists, I would be 
> grateful if someone would redirect me to it.
>
It doesn't exist unless someone has built it internally and is keeping it 
for themselves (not likely). Fergal's suggestion of lein-midje-doc is 
probably the closest.
 

> Here are *my thoughts on this :*
>
>1. Clojure doc-strings, although they are quite handy as reminders and 
>for doc-indexation, are *too raw a content*. Even when they are done 
>right, they tend to be cumbersome, and it's too bad to have such concise 
>code drown in the middle of so much documentation. What's more, I believe 
>that when programmers program a function (or anything), they tend to think 
>more about the implementation than the (uninformed) usage, so they have 
>little incentive to make it right.
>
> I think doc strings are necessary, but not sufficient. I think there *is*a 
> role for documentation in the code, otherwise you end up duplicating 
documentation in the separate docs and docstrings, or in comments, so a 
Clojure documentation framework/solution probably out to be able to make 
use of doc strings by pulling out their content. It ought to also pull out 
things like :pre and :post. It ought to use the code to make writing the 
docs as easy and boilerplate free as possible. But again, when you need a 
lot of docs, tutorials, etc. putting that stuff directly in the code is a 
mess.

>
>1. Building on 1. having a system where documentation and programs 
>live in separate files, in the same way as tests, would enforce a healthy 
>separation of concerns. Importantly, it would make life much easier on the 
>Version Control perspective.
>
> Yes. And just how tests refer back to the code they are testing. I think 
docs need to be able to refer back to the vars/atoms/functions/doc strings 
etc. of the code they are documenting.
 

>
>1. Documentation should probably be made differently than what people 
>have got accustomed to by classical languages. Because you seldom find 
>types, and because IMHO Clojure programs are formed more by factoring out 
>recurring mechanisms in cod

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

Tim, I am in full support of the approach to documentation that you 
describe, for individuals and organizations that feel that it best supports 
their needs.  It's a good approach.  I don't favor requiring an entire 
programming community to follow it.  That's too much of an imposition.  I 
do like the idea of more minimal norms for a community.  Docstrings are a 
good start, but I can see the benefits of slightly more systematic norms or 
tools for (e.g.) docstrings, or references to more information.  I think 
that it's a matter of degree.  Minimal norms shouldn't require too much of 
programmers.  It should be pretty obvious to any experienced programmer 
that such a norm will be worth following, and it should be easy to follow 
it.  Maybe there should also be norms for more elaborate kinds of 
documentation for those organizations that want more elaborate kinds--that 
way, there will be some uniformity among such organizations.  That might be 
the best of both worlds: An adequate minimal norm for documentation, with 
easy-to-use tool support, plus norms and tool support for extensions to the 
minimal norm.

On Wednesday, April 30, 2014 2:09:04 AM UTC-5, da...@axiom-developer.org 
wrote:
>
> > Imagine you're reading through some documentation and you notice a 
> > problem. Maybe a typo, or something out of date, or something that's 
> > confusing that you could explain better. In one scenario there's a "git 
> > clone" link in the sidebar to a repository that contains a bunch of 
> > markdown files. In another scenario there's an HTML rendering generated 
> > from a literate programming project where the prose is intermixed with 
> the 
> > code and requires a specific version of org-mode and the knowledge of 
> how 
> > to "untangle" something in order to render it. 
>
> This is a focus on the technology which I'm reluctant to do, mostly 
> because I have strong opinions about it. I will say from experience that 
> any technology that separates code from explanation will fail. If we 
> focus on what information we require and what structure has to be placed 
> on that information so it can be understood THEN we can ask about the 
> technologies and what they support. 
>
> > Can I ask, quite seriously and not intending any sarcasm, what you mean 
> > by "detracts from what's important"? 
> > 
> > For me, "what's important" is to communicate ideas, designs, and details 
> > from one developer to another so that others can maintain, modify, and 
> > extend what exists. I've already held forth on what I think that implies 
> > so I won't bore you with it. 
>
>
> Consider Clojure's primary data structure implementation. It is 
> basically an immutable, log32, red-black tree. For some people that is 
> more than sufficient, especially if they have been working in the code 
> base for years. 
>
> For others, especially as a developer new to the project, there is a lot 
> to know. Without this information it is very difficult to contribute. 
>
> A new developer needs an introduction to the IDEA of immutable data 
> structures with a reference to Okasaki's thesis which is online at 
> http://www.cs.cmu.edu/~rwh/theses/okasaki.pdf (a bibliography). 
>
> A new developer needs to know that the DESIGN of Clojure relies on these 
> immutable data structures so they don't introduce any "quick and 
> efficient" hacks that violate the design. (a Clojure overview) 
>
> A new developer needs to know WHAT a red-black tree is, WHY it was 
> chosen, and HOW Clojure maps user-visible data structures to them.   
> (the chapter on this particular data structure) 
>
> A new developer needs to know the IMPLICATIONS of the choice of log32 
> since it defines the efficiency. (the design constraints section and 
> the algorithmic analysis section) 
>
> A new developer needs to know HOW to update a log32 immutable red-black 
> tree.  (a pseudocode explanation with pictures) 
>
> A new developer needs to know HOW the log32 red-black tree is 
> implemented.  It is not immediately obvious how the 5-bit chunks are 
> mapped into a 32 bit word. If the task was to re-implement it on a 64 
> bit word they'd have to know the details to understand the code.  (the 
> actual code with explanations of the variables) 
>
> If the new developer's task is to modify the code for a 64 bit 
> architecture they would need a way to find the code (the table of 
> contents) and places where this information is mentioned (an index). 
> All of the places where it is written need to be properly updated. 
>
> Even if we focus strictly on what a new developer needs to know 
> we end up with something that smells a lot like a book. From the 
> above we see the need for 
>
>   1) a bibliography 
>   2) a Clojure overview 
>   3) a chapter focus on this data structure 
>   4) sections on design constraints and algorithmic analysis 
>   5) a section of pseudocode with pictures 
>   6) a section with code and details of the actual implementation 
>   7) a table of

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

Phil Hagelberg  writes:

> On Saturday, April 26, 2014 9:21:26 PM UTC-7, Mars0i wrote:
>> I like the general idea of the Valentin's proposal, but I don't
>> understand every bit of it.  It sounds complicated.  Personally, I'd
>> rather see something that's relatively simple, and good enough, than
>> something that's perfect but unwieldy.  If it's too difficult, people
>> won't use it, or they'll waste time, or feel that the Clojure
>> community expects them to spend too much time on something that
>> detracts from what's important.
>
> Double-inc[1] on this. Clojure needs people who care about documentation 
> far more than it needs another documentation system. Don't try to apply a 
> technical solution to a social problem.


Consider this argument, of the same form.

What the JVM needs is people who care about writing good code far more
than it needs another JVM hosted language. Don't try and apply a
technical solution to a social problem.


Following this logic, we can just dump Clojure and use Java; in fact, if
we do this, we will achieve a better documentation system than we have
at the moment, because javadoc is better than Clojure's system.

Of course, technical solutions don't solve all problems, and authoring
documentation is difficult to start off with; but Clojure's current
system -- an unstructured string -- is not a good tool. Compare Emacs
doc

Compare these two strings:

Returns a new seq where x is the first element and seq is
the rest.

Create a new cons, give it CAR and CDR as components, and return it.


In the latter, we can distinguish CAR and CDR as parameters. In the
former, cannot. We could look at arglist

:arglists '([x seq])

which tells us. However, we have "a new seq" and "seq is the rest" --
one refering to the formal parameter and the other refering to the
clojure abstraction. And neither refering to clojure.core/seq which we
might otherwise want to hyperlink to.

We could change it to this

Returns a new object implementing the ISeq interface, where the formal
parameter x is the first element and the formal parameter seq is the
rest.

which avoids the ambiguity, but this is long winded.

We need some structure, or at least conventions in Clojure
documentation. The lack of this is the technical problem. That we have
many potential technical solutions is social problem, not that we have
any.

Phil



-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Tim Daly]

> Imagine you're reading through some documentation and you notice a
> problem. Maybe a typo, or something out of date, or something that's
> confusing that you could explain better. In one scenario there's a "git
> clone" link in the sidebar to a repository that contains a bunch of
> markdown files. In another scenario there's an HTML rendering generated
> from a literate programming project where the prose is intermixed with the
> code and requires a specific version of org-mode and the knowledge of how
> to "untangle" something in order to render it.

This is a focus on the technology which I'm reluctant to do, mostly
because I have strong opinions about it. I will say from experience that
any technology that separates code from explanation will fail. If we
focus on what information we require and what structure has to be placed
on that information so it can be understood THEN we can ask about the
technologies and what they support.

> Can I ask, quite seriously and not intending any sarcasm, what you mean 
> by "detracts from what's important"? 
>
> For me, "what's important" is to communicate ideas, designs, and details 
> from one developer to another so that others can maintain, modify, and 
> extend what exists. I've already held forth on what I think that implies 
> so I won't bore you with it. 


Consider Clojure's primary data structure implementation. It is
basically an immutable, log32, red-black tree. For some people that is
more than sufficient, especially if they have been working in the code
base for years.

For others, especially as a developer new to the project, there is a lot
to know. Without this information it is very difficult to contribute.

A new developer needs an introduction to the IDEA of immutable data
structures with a reference to Okasaki's thesis which is online at
http://www.cs.cmu.edu/~rwh/theses/okasaki.pdf (a bibliography).

A new developer needs to know that the DESIGN of Clojure relies on these
immutable data structures so they don't introduce any "quick and
efficient" hacks that violate the design. (a Clojure overview)

A new developer needs to know WHAT a red-black tree is, WHY it was
chosen, and HOW Clojure maps user-visible data structures to them.  
(the chapter on this particular data structure)

A new developer needs to know the IMPLICATIONS of the choice of log32
since it defines the efficiency. (the design constraints section and
the algorithmic analysis section)

A new developer needs to know HOW to update a log32 immutable red-black
tree.  (a pseudocode explanation with pictures)

A new developer needs to know HOW the log32 red-black tree is
implemented.  It is not immediately obvious how the 5-bit chunks are
mapped into a 32 bit word. If the task was to re-implement it on a 64
bit word they'd have to know the details to understand the code.  (the
actual code with explanations of the variables)

If the new developer's task is to modify the code for a 64 bit
architecture they would need a way to find the code (the table of
contents) and places where this information is mentioned (an index). 
All of the places where it is written need to be properly updated.

Even if we focus strictly on what a new developer needs to know
we end up with something that smells a lot like a book. From the
above we see the need for 

  1) a bibliography
  2) a Clojure overview
  3) a chapter focus on this data structure
  4) sections on design constraints and algorithmic analysis
  5) a section of pseudocode with pictures
  6) a section with code and details of the actual implementation
  7) a table of contents
  8) an index

And that's only a few dozen lines of the Clojure source code.

Now we know what information we require and what structure has to be
placed on that information so it can be understood, managed, and kept up
to date with the code. NOW let's talk about technologies that support
these requirements.

We can examine the ideas for possible technologies to properly organize
the above information. Do inline comments in source code files work?
Does a Javadoc kind of technology work? Does a wiki on an external
website work? Do separate markdown files in the directory tree work? Do
we create videos to explain code?  Do any of these technologies
integrate with the normal edit-compile-test code developement cycle?
Does changing the code generate an immediate expectation to update
the associated words?

I would claim that only a technology that is fully integrated into the
developer's main line, day-to-day work cycle will ensure that the
associated information up to date.

Checking in code ought to require a review of the associated 
information to ensure that it is up to date; essentially the role
of an "editor-in-chief" whose job it is to maintain high quality,
READABLE, natural language.

Our standard needs to be that anyone can read the words and KNOW
that the code is correct, complete, efficent, and well integrated
with the rest of the design.

This isn't really a tec

Re: Proposing a new Clojure documentation system (in Clojure)

[Atamert Ölçgen]

On Wed, Apr 30, 2014 at 4:18 AM, Phil Hagelberg  wrote:

> On Tuesday, April 29, 2014 9:08:48 PM UTC-7, Mars0i wrote:
>>
>> Oh, sorry--you also asked what I meant by "detracts from" what's
>> important.  If a documentation formatting/organizing/coding system required
>> learning a lot, figuring out a lot, adding information that is unlikely to
>> be helpful
>>
>
> Imagine you're reading through some documentation and you notice a
> problem. Maybe a typo, or something out of date, or something that's
> confusing that you could explain better. In one scenario there's a "git
> clone" link in the sidebar to a repository that contains a bunch of
> markdown files. In another scenario there's an HTML rendering generated
> from a literate programming project where the prose is intermixed with the
> code and requires a specific version of org-mode and the knowledge of how
> to "untangle" something in order to render it.
>
> Guess which one is going to get improved.
>

The answer is not immediately obvious to me.

Since I don't use emacs, I would probably have found the former easier.
Having said that, perhaps everybody else who are capable of contributing
are already comfortable with the literal programming tool. Or perhaps I
would find out it doesn't take too much effort to contribute once I learn
the basics. And perhaps this kind of documentation is works much better for
this specific project, seeing the code and the docs side by side. I'm going
to risk saying, perhaps there is an inversely proportional relationship
between markdown proficiency/preference and contributed value in a
technical community.

I'm not saying documentation as a bunch of markdown files sucks. I'm just
not sure if it would shown to be objectively superior to the less
accessible literate programming, in the context of the quality of
contributions and perhaps the health of the project.




>
> -Phil
>
> --
> 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 unsubscribe from this group and stop receiving emails from it, send an
> email to clojure+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>



-- 
Kind Regards,
Atamert Ölçgen

-+-
--+
+++

www.muhuk.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
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phil Hagelberg]

On Tuesday, April 29, 2014 9:08:48 PM UTC-7, Mars0i wrote:
>
> Oh, sorry--you also asked what I meant by "detracts from" what's 
> important.  If a documentation formatting/organizing/coding system required 
> learning a lot, figuring out a lot, adding information that is unlikely to 
> be helpful
>

Imagine you're reading through some documentation and you notice a problem. 
Maybe a typo, or something out of date, or something that's confusing that 
you could explain better. In one scenario there's a "git clone" link in the 
sidebar to a repository that contains a bunch of markdown files. In another 
scenario there's an HTML rendering generated from a literate programming 
project where the prose is intermixed with the code and requires a specific 
version of org-mode and the knowledge of how to "untangle" something in 
order to render it.

Guess which one is going to get improved.

-Phil

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

On Tuesday, April 29, 2014 11:01:46 PM UTC-5, Mars0i wrote:
>
> On Tuesday, April 29, 2014 10:47:58 PM UTC-5, da...@axiom-developer.orgwrote:
>>
>> Phil, 
>>
>> > I like the general idea of the Valentin's proposal, but I don't 
>> > understand every bit of it.  It sounds complicated.  Personally, I'd 
>> > rather see something that's relatively simple, and good enough, than 
>> > something that's perfect but unwieldy.  If it's too difficult, people 
>> > won't use it, or they'll waste time, or feel that the Clojure 
>> > community expects them to spend too much time on something that 
>> > detracts from what's important. 
>>
>> Can I ask, quite seriously and not intending any sarcasm, what you mean 
>> by "detracts from what's important"? 
>>
>> For me, "what's important" is to communicate ideas, designs, and details 
>> from one developer to another so that others can maintain, modify, and 
>> extend what exists. I've already held forth on what I think that implies 
>> so I won't bore you with it. 
>>
>> What I don't understand is your criteria for "what's important" and 
>> how that translates to action. 
>>
>> If we can agree on "what's important" then the technical details would 
>> have common criteria for "simple and good enough vs something that's 
>> perfect but unwieldy". 
>>
>> Tim Daly 
>>
>
> We agree. 
>

Oh, sorry--you also asked what I meant by "detracts from" what's 
important.  If a documentation formatting/organizing/coding system required 
learning a lot, figuring out a lot, adding information that is unlikely to 
be helpful, but could easily be replaced with something that's trivial to 
use, produce output that's less pretty, and that might require using a 
search function more often, but nevertheless helps to support good, 
thorough documentation (maybe terse sometimes, but still, it gives you what 
you need) that helps other developers (or oneself, later) to understand 
code whose meaning isn't obvious, then I'd favor the latter.  Maybe no one 
is proposing what the former.  I didn't understand the proposal, so I 
didn't know.  (Aside about obviousness: My own standard for obviousness is 
more restrictive--i.e. fewer things are obvious--than some programmers, I 
think.)

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

On Tuesday, April 29, 2014 10:47:58 PM UTC-5, da...@axiom-developer.org 
wrote:
>
> Phil, 
>
> > I like the general idea of the Valentin's proposal, but I don't 
> > understand every bit of it.  It sounds complicated.  Personally, I'd 
> > rather see something that's relatively simple, and good enough, than 
> > something that's perfect but unwieldy.  If it's too difficult, people 
> > won't use it, or they'll waste time, or feel that the Clojure 
> > community expects them to spend too much time on something that 
> > detracts from what's important. 
>
> Can I ask, quite seriously and not intending any sarcasm, what you mean 
> by "detracts from what's important"? 
>
> For me, "what's important" is to communicate ideas, designs, and details 
> from one developer to another so that others can maintain, modify, and 
> extend what exists. I've already held forth on what I think that implies 
> so I won't bore you with it. 
>
> What I don't understand is your criteria for "what's important" and 
> how that translates to action. 
>
> If we can agree on "what's important" then the technical details would 
> have common criteria for "simple and good enough vs something that's 
> perfect but unwieldy". 
>
> Tim Daly 
>

We agree. 

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phil Hagelberg]

On Tuesday, April 29, 2014 8:47:58 PM UTC-7, da...@axiom-developer.org 
wrote:
> Can I ask, quite seriously and not intending any sarcasm, what you mean 
> by "detracts from what's important"?

What's important is writing clear explanatory prose.

This is really hard to do for a lot of reasons, but none of them are 
technical. Organizing your thoughts is hard. Thinking like a newcomer is 
very hard. Achieving clarity on any subject matter is hard. Knowing when to 
update is hard. Editing is hard. (And you can't effectively act as your own 
editor.)

Putting words into a file on disk is easy, and rendering those words in a 
way that is convenient for others to read is very easy.

-Phil

ps. I hope that anyone who's interested in improving the documentation 
situation will look to Jacob Kaplan-Moss's articles on the topic, which do 
a better job of laying out the problem than I could 
do: http://jacobian.org/writing/what-to-write/

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Tim Daly]

Phil,

> I like the general idea of the Valentin's proposal, but I don't
> understand every bit of it.  It sounds complicated.  Personally, I'd
> rather see something that's relatively simple, and good enough, than
> something that's perfect but unwieldy.  If it's too difficult, people
> won't use it, or they'll waste time, or feel that the Clojure
> community expects them to spend too much time on something that
> detracts from what's important.

Can I ask, quite seriously and not intending any sarcasm, what you mean
by "detracts from what's important"? 

For me, "what's important" is to communicate ideas, designs, and details
from one developer to another so that others can maintain, modify, and
extend what exists. I've already held forth on what I think that implies
so I won't bore you with it.

What I don't understand is your criteria for "what's important" and 
how that translates to action.

If we can agree on "what's important" then the technical details would
have common criteria for "simple and good enough vs something that's
perfect but unwieldy".

Tim Daly


-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phil Hagelberg]

On Saturday, April 26, 2014 9:21:26 PM UTC-7, Mars0i wrote:
> I like the general idea of the Valentin's proposal, but I don't
> understand every bit of it.  It sounds complicated.  Personally, I'd
> rather see something that's relatively simple, and good enough, than
> something that's perfect but unwieldy.  If it's too difficult, people
> won't use it, or they'll waste time, or feel that the Clojure
> community expects them to spend too much time on something that
> detracts from what's important.

Double-inc[1] on this. Clojure needs people who care about documentation 
far more than it needs another documentation system. Don't try to apply a 
technical solution to a social problem.

-Phil

[1] - or dinc, as I like to call it.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Phillip Lord]

I struggled with Clojure's documentation system while writing 
https://github.com/phillord/tawny-owl. The problem here is that I am
using an underlying Java library; in the ideal world, I would like
documentation on vars to come from the Object held in the var. But there
is no way to achieve this in Clojure because it's a :doc string in the
metadata.

Now, with tawny-owl, the documentation is still not very good; I would
like to improve it, but many parts of the documentation are not specific
to Clojure, but need to relate to the problem domain for the libary. And
I would like to be able to publish that part of the documentation
independently from Clojure -- so being able to transclude external files
would be very useful indeed.

Even on a simple level, I get frustrated that, in clojure, there is no
typographical way to distinguish a parameter, a function and a normal
word.

One simple way to allow this would be to let :doc take a one-arg closure
(taking the var).

Phil

Val Waeselynck  writes:

> Hello to all,
>
> *Short version :* I think Clojure needs a documentation system in Clojure, 
> I would like to know if some efforts exist in that direction, and I am 
> willing to create it / contribute to it.
>
> *Long version :*
>
> I've been thinking for a while that the Clojure community could benefit a 
> lot from a more sophisticated and ergonomic documentation system. 
>
> I have seen some existing plugins like lein-sphinx, but I think it would be 
> really good to have documentation that would be written in Clojure, for the 
> following reasons :
>
>- we're all very fond of Clojure data structures and their syntax. (I 
>don't know about you, but I find that even HTML looks better in
> Clojurethan in HTML). Plus, Clojure
> programmers already know how to edit them.
>- (better reason) The facts that Vars are first-class citizens and that 
>symbols can be referred explicitly with hardly any ceremony (macros) are a 
>exceptional opportunity to make smart and highly-structured documentation 
>very easily.
>- if it's in Clojure, Clojure programmers can seamlessly build *ad
> hoc*documentation functionality on top of it to suit their own particular
> needs.
>
> I haven't found anything of the like yet, and if it exists, I would be 
> grateful if someone would redirect me to it.
>
> Here are *my thoughts on this :*
>
>1. Clojure doc-strings, although they are quite handy as reminders and 
>for doc-indexation, are *too raw a content*. Even when they are done 
>right, they tend to be cumbersome, and it's too bad to have such concise 
>code drown in the middle of so much documentation. What's more, I believe 
>that when programmers program a function (or anything), they tend to think 
>more about the implementation than the (uninformed) usage, so they have 
>little incentive to make it right.
>2. Building on 1. having a system where documentation and programs live 
>in separate files, in the same way as tests, would enforce a healthy 
>separation of concerns. Importantly, it would make life much easier on the 
>Version Control perspective.
>3. Documentation should probably be made differently than what people 
>have got accustomed to by classical languages. Because you seldom find 
>types, and because IMHO Clojure programs are formed more by factoring out 
>recurring mechanisms in code than from implementing intellectual 
>abstractions, the relevant concepts tend not to be obvious in the code. 
>Since in Clojure we program with verbs, not
> nouns,
>I think *documentation is best made by example*.
>4. Documentation of a Var should not be a formal description of what it 
>is and what it does with some cryptically-named variables. *Every bit of 
>documentation should be a micro-tutorial*. Emphasis should be put on 
>usage, examples, tips, pitfalls, howtos.
>5. There should be structure in the documentation, and it shouldn't be 
>just :see-also links - *there should be semantics* in it.  For example, 
>some functions/macros are really meant to be nothing but shorthands for 
>calling other functions : that kind of relationship should be explicitly 
>documented.
>6. Documentation should not be just information about each separate Var 
>in a namespace. There should be a hierarchy to make the most useful 
>elements of an API more obvious. Also, adding cross-vars documentation 
>elements such as tags and topics could make it easier to navigate and 
>understand.
>7. *Documentation in the REPL is great*, it was one of the very good 
>surprises when I started learning Clojure. However, a rich and 
> good-looking 
>presentation like in Javadocs would be welcome too.
>
> Of course, all of the above are just vague principles. Here is *some 
> funct

Re: Proposing a new Clojure documentation system (in Clojure)

[Fergal Byrne]

Hi Valentin,

Thanks for starting such an excellent discussion, and your initial posting
is very well put. I think you should talk to Chris Zheng who has developed
a tool called lein-midje-doc [1] which it seems answers much of your
questions. I've been using it for months now and it is the centrepiece of
my development workflow.

lein-midje-doc combines the Midje test framework with a literate
programming model. Essentially you write documentation (as you describe) in
Clojure, with your text in Markdown, structured using Clojure data
structures, and sample code which shows the reader how to use the code. The
sample code can be either just that (ie it produces a code block but is
merely pretty-ptinted text) by putting the sample code in a (comment ...)
form, or else executable doumentation/test code of the form:

(+ 1 2 3) => 6

by putting the sample code in a Midje (fact ...) form.

Here's an example doc [2] I produced recently which compares two encoders
for my Clortex project. As you can see, it's a mini-paper which goes
through the shortcomings of an existing encoder, then argues for, explains
and demonstrates a new design. The doc has an include directive which pulls
in the source code for the new encoder in the middle.

In addition to this, docstrings are still hugely useful and should form
part of the workflow for accessing quick summary and usage information on
functions. I use Marginalia [3] to convert docstrings into a side-by-side
doc-and-code presentation.

Finally, I'm using the wonderful hoplon-reveal-js [4] to produce beautiful
presentations about the work and the software. It's all done in
ClojureScript and is a huge step in the direction you're talking about.

I would also point you to Gorilla REPL [5] and Session [6] for another take
on doing literate programming and mixing markup with code in Clojure.
Hopefully there's some way these guys can combine their projects, the
combination would be scary!

Regards

Fergal

[1] https://github.com/zcaudate/lein-midje-doc
[2] http://fergalbyrne.github.io/rdse.html
[3] https://github.com/gdeer81/marginalia
[4] https://github.com/oubiwann/hoplon-reveal-js
[5] https://github.com/JonyEpsilon/gorilla-repl
[6] https://github.com/kovasb/session




On Sun, Apr 27, 2014 at 5:21 AM, Mars0i  wrote:

> Some thoughts:
>
> Having concise documentation in the same place as the code minimizes a
> certain kind of work:  I want my functions to be commented in the source
> file so that someone reading it later (maybe me) will quickly understand
> what they're supposed to do.  If Clojure didn't have docstrings, I'd put
> similar information, although maybe more terse, in comments.  As it is, I
> just write the docstring, and I've accomplished two things in one.  If all
> of the documentation was in another file, I'd have to do at least 1.5 times
> more work just to produce the kind of docstrings I produce now.
>
> Some docstrings (e.g. for xy-plot in Incanter) are too long for convenient
> use at a repl.  So I appreciate the idea of providing different levels of
> documentation.  What's displayed by default at a prompt should be short.
>
> I like the general idea of the Valentin's proposal, but I don't understand
> every bit of it.  It sounds complicated.  Personally, I'd rather see
> something that's relatively simple, and good enough, than something that's
> perfect but unwieldy.  If it's too difficult, people won't use it, or
> they'll waste time, or feel that the Clojure community expects them to
> spend too much time on something that detracts from what's important.  I am
> someone who I think has put more time into documentation more than most of
> the programmers I've worked with.  I'm in favor of encouraging more
> documentation of code.  But documentation tools should not make the process
> much harder than it is.  Ideally, they should make it easier, but some
> extra cost is worthwhile for extra payoff later.
>
> --
> 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 unsubscribe from this group and stop receiving emails from it, send an
> email to clojure+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>



-- 

Fergal Byrne, Brenter IT

Author, Real Machine Intelligence with Clortex and NuPIC
https://leanpub.com/realsmartmachines

Speaking on Clortex and HTM/CLA at euroClojure Krakow, June 2014:
http://euroclojure.com/2014/

http://inbits.com - Better Living through
Thoughtful Technology
http://ie.linkedin.com/in/fe

Re: Proposing a new Clojure documentation system (in Clojure)

[Mars0i]

Some thoughts:

Having concise documentation in the same place as the code minimizes a 
certain kind of work:  I want my functions to be commented in the source 
file so that someone reading it later (maybe me) will quickly understand 
what they're supposed to do.  If Clojure didn't have docstrings, I'd put 
similar information, although maybe more terse, in comments.  As it is, I 
just write the docstring, and I've accomplished two things in one.  If all 
of the documentation was in another file, I'd have to do at least 1.5 times 
more work just to produce the kind of docstrings I produce now.

Some docstrings (e.g. for xy-plot in Incanter) are too long for convenient 
use at a repl.  So I appreciate the idea of providing different levels of 
documentation.  What's displayed by default at a prompt should be short.

I like the general idea of the Valentin's proposal, but I don't understand 
every bit of it.  It sounds complicated.  Personally, I'd rather see 
something that's relatively simple, and good enough, than something that's 
perfect but unwieldy.  If it's too difficult, people won't use it, or 
they'll waste time, or feel that the Clojure community expects them to 
spend too much time on something that detracts from what's important.  I am 
someone who I think has put more time into documentation more than most of 
the programmers I've worked with.  I'm in favor of encouraging more 
documentation of code.  But documentation tools should not make the process 
much harder than it is.  Ideally, they should make it easier, but some 
extra cost is worthwhile for extra payoff later.

-- 
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 unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposing a new Clojure documentation system (in Clojure)

[Val Waeselynck]

Fair points. Well, leaving the possibility to document the code from just 
anywhere is what I had in mind.

Le samedi 26 avril 2014 22:52:41 UTC+2, Jason Felice a écrit :
>
> Personally, I like documentation in the same place as the code it 
> documents And I'd love to have the  tests in the same file as well.
>
> In both cases, I think the things are highly coupled by their nature, and 
> therefore I want them together (OK, tests aren't always - in the cases they 
> aren't, put them in a separate file).  I've reminded people that the SRP 
> ("any piece of code should have one reason to change") implies the 
> converse, which I phrase as "Code which changes together, stays together."
>
> That said, I like the idea of more structured documentation.  (Possibly 
> including test cases!  Python has test runners which verify examples in doc 
> strings, for example.)
> On Apr 26, 2014 4:31 PM, "Gary Trakhman" > 
> wrote:
>
>> This is a lovely idea. 
>>
>> I think prismatic schema is one well-accepted way to document data 
>> shapes, but it's expected to be used inline. It would be nice to have 
>> flexibility in what description systems are used in addition to flexibility 
>> of where the docs live. 
>>
>> I agree that being able to see and reason about bare code with no hassle 
>> is a (personal) demotivator for documentation, but where the docs live 
>> should be up to the implementor.  Having a code-based system means we can 
>> use and improve existing runtime tooling to navigate and interact with it. 
>>  This would make a great cider middleware :-).
>>
>> On Saturday, April 26, 2014, Val Waeselynck 
>> > 
>> wrote:
>>
>>> Hello to all,
>>>
>>> *Short version :* I think Clojure needs a documentation system in 
>>> Clojure, I would like to know if some efforts exist in that direction, and 
>>> I am willing to create it / contribute to it.
>>>
>>> *Long version :*
>>>
>>> I've been thinking for a while that the Clojure community could benefit 
>>> a lot from a more sophisticated and ergonomic documentation system. 
>>>
>>> I have seen some existing plugins like lein-sphinx, but I think it would 
>>> be really good to have documentation that would be written in Clojure, for 
>>> the following reasons :
>>>
>>>- we're all very fond of Clojure data structures and their syntax. 
>>>(I don't know about you, but I find that even HTML looks better in 
>>>Clojure  than in HTML). Plus, 
>>>Clojure programmers already know how to edit them.
>>>- (better reason) The facts that Vars are first-class citizens and 
>>>that symbols can be referred explicitly with hardly any ceremony 
>>> (macros) 
>>>are a exceptional opportunity to make smart and highly-structured 
>>>documentation very easily. 
>>>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
>>>hoc* documentation functionality on top of it to suit their own 
>>>particular needs.
>>>
>>> I haven't found anything of the like yet, and if it exists, I would be 
>>> grateful if someone would redirect me to it.
>>>
>>> Here are *my thoughts on this :*
>>>
>>>1. Clojure doc-strings, although they are quite handy as reminders 
>>>and for doc-indexation, are *too raw a content*. Even when they are 
>>>done right, they tend to be cumbersome, and it's too bad to have such 
>>>concise code drown in the middle of so much documentation. What's more, 
>>> I 
>>>believe that when programmers program a function (or anything), they 
>>> tend 
>>>to think more about the implementation than the (uninformed) usage, so 
>>> they 
>>>have little incentive to make it right.
>>>2. Building on 1. having a system where documentation and programs 
>>>live in separate files, in the same way as tests, would enforce a 
>>> healthy 
>>>separation of concerns. Importantly, it would make life much easier on 
>>> the 
>>>Version Control perspective. 
>>>3. Documentation should probably be made differently than what 
>>>people have got accustomed to by classical languages. Because you seldom 
>>>find types, and because IMHO Clojure programs are formed more by 
>>> factoring 
>>>out recurring mechanisms in code than from implementing intellectual 
>>>abstractions, the relevant concepts tend not to be obvious in the code. 
>>>Since in Clojure we program with verbs, not 
>>> nouns,
>>>  
>>>I think *documentation is best made by example*.
>>>4. Documentation of a Var should not be a formal description of what 
>>>it is and what it does with some cryptically-named variables. *Every 
>>>bit of documentation should be a micro-tutorial*. Emphasis should be 
>>>put on usage, examples, tips, pitfalls, howtos. 
>>>5. There should be structure in the documentation, and it shouldn't 
>>>be just :see-also links - *there should be semantics* in i

Re: Proposing a new Clojure documentation system (in Clojure)

[Jason Felice]

Personally, I like documentation in the same place as the code it
documents And I'd love to have the  tests in the same file as well.

In both cases, I think the things are highly coupled by their nature, and
therefore I want them together (OK, tests aren't always - in the cases they
aren't, put them in a separate file).  I've reminded people that the SRP
("any piece of code should have one reason to change") implies the
converse, which I phrase as "Code which changes together, stays together."

That said, I like the idea of more structured documentation.  (Possibly
including test cases!  Python has test runners which verify examples in doc
strings, for example.)
On Apr 26, 2014 4:31 PM, "Gary Trakhman"  wrote:

> This is a lovely idea.
>
> I think prismatic schema is one well-accepted way to document data shapes,
> but it's expected to be used inline. It would be nice to have flexibility
> in what description systems are used in addition to flexibility of where
> the docs live.
>
> I agree that being able to see and reason about bare code with no hassle
> is a (personal) demotivator for documentation, but where the docs live
> should be up to the implementor.  Having a code-based system means we can
> use and improve existing runtime tooling to navigate and interact with it.
>  This would make a great cider middleware :-).
>
> On Saturday, April 26, 2014, Val Waeselynck  wrote:
>
>> Hello to all,
>>
>> *Short version :* I think Clojure needs a documentation system in
>> Clojure, I would like to know if some efforts exist in that direction, and
>> I am willing to create it / contribute to it.
>>
>> *Long version :*
>>
>> I've been thinking for a while that the Clojure community could benefit a
>> lot from a more sophisticated and ergonomic documentation system.
>>
>> I have seen some existing plugins like lein-sphinx, but I think it would
>> be really good to have documentation that would be written in Clojure, for
>> the following reasons :
>>
>>- we're all very fond of Clojure data structures and their syntax. (I
>>don't know about you, but I find that even HTML looks better in
>>Clojure  than in HTML). Plus,
>>Clojure programmers already know how to edit them.
>>- (better reason) The facts that Vars are first-class citizens and
>>that symbols can be referred explicitly with hardly any ceremony (macros)
>>are a exceptional opportunity to make smart and highly-structured
>>documentation very easily.
>>- if it's in Clojure, Clojure programmers can seamlessly build *ad
>>hoc* documentation functionality on top of it to suit their own
>>particular needs.
>>
>> I haven't found anything of the like yet, and if it exists, I would be
>> grateful if someone would redirect me to it.
>>
>> Here are *my thoughts on this :*
>>
>>1. Clojure doc-strings, although they are quite handy as reminders
>>and for doc-indexation, are *too raw a content*. Even when they are
>>done right, they tend to be cumbersome, and it's too bad to have such
>>concise code drown in the middle of so much documentation. What's more, I
>>believe that when programmers program a function (or anything), they tend
>>to think more about the implementation than the (uninformed) usage, so 
>> they
>>have little incentive to make it right.
>>2. Building on 1. having a system where documentation and programs
>>live in separate files, in the same way as tests, would enforce a healthy
>>separation of concerns. Importantly, it would make life much easier on the
>>Version Control perspective.
>>3. Documentation should probably be made differently than what people
>>have got accustomed to by classical languages. Because you seldom find
>>types, and because IMHO Clojure programs are formed more by factoring out
>>recurring mechanisms in code than from implementing intellectual
>>abstractions, the relevant concepts tend not to be obvious in the code.
>>Since in Clojure we program with verbs, not 
>> nouns,
>>I think *documentation is best made by example*.
>>4. Documentation of a Var should not be a formal description of what
>>it is and what it does with some cryptically-named variables. *Every
>>bit of documentation should be a micro-tutorial*. Emphasis should be
>>put on usage, examples, tips, pitfalls, howtos.
>>5. There should be structure in the documentation, and it shouldn't
>>be just :see-also links - *there should be semantics* in it.  For
>>example, some functions/macros are really meant to be nothing but
>>shorthands for calling other functions : that kind of relationship should
>>be explicitly documented.
>>6. Documentation should not be just information about each separate
>>Var in a namespace. There should be a hierarchy to make the most useful
>>elements of an API mor

Re: Proposing a new Clojure documentation system (in Clojure)

[Gary Trakhman]

This is a lovely idea.

I think prismatic schema is one well-accepted way to document data shapes,
but it's expected to be used inline. It would be nice to have flexibility
in what description systems are used in addition to flexibility of where
the docs live.

I agree that being able to see and reason about bare code with no hassle is
a (personal) demotivator for documentation, but where the docs live should
be up to the implementor.  Having a code-based system means we can use and
improve existing runtime tooling to navigate and interact with it.  This
would make a great cider middleware :-).

On Saturday, April 26, 2014, Val Waeselynck  wrote:

> Hello to all,
>
> *Short version :* I think Clojure needs a documentation system in
> Clojure, I would like to know if some efforts exist in that direction, and
> I am willing to create it / contribute to it.
>
> *Long version :*
>
> I've been thinking for a while that the Clojure community could benefit a
> lot from a more sophisticated and ergonomic documentation system.
>
> I have seen some existing plugins like lein-sphinx, but I think it would
> be really good to have documentation that would be written in Clojure, for
> the following reasons :
>
>- we're all very fond of Clojure data structures and their syntax. (I
>don't know about you, but I find that even HTML looks better in 
> Clojurethan in HTML). Plus, Clojure 
> programmers already know how to edit them.
>- (better reason) The facts that Vars are first-class citizens and
>that symbols can be referred explicitly with hardly any ceremony (macros)
>are a exceptional opportunity to make smart and highly-structured
>documentation very easily.
>- if it's in Clojure, Clojure programmers can seamlessly build *ad 
> hoc*documentation functionality on top of it to suit their own particular 
> needs.
>
> I haven't found anything of the like yet, and if it exists, I would be
> grateful if someone would redirect me to it.
>
> Here are *my thoughts on this :*
>
>1. Clojure doc-strings, although they are quite handy as reminders and
>for doc-indexation, are *too raw a content*. Even when they are done
>right, they tend to be cumbersome, and it's too bad to have such concise
>code drown in the middle of so much documentation. What's more, I believe
>that when programmers program a function (or anything), they tend to think
>more about the implementation than the (uninformed) usage, so they have
>little incentive to make it right.
>2. Building on 1. having a system where documentation and programs
>live in separate files, in the same way as tests, would enforce a healthy
>separation of concerns. Importantly, it would make life much easier on the
>Version Control perspective.
>3. Documentation should probably be made differently than what people
>have got accustomed to by classical languages. Because you seldom find
>types, and because IMHO Clojure programs are formed more by factoring out
>recurring mechanisms in code than from implementing intellectual
>abstractions, the relevant concepts tend not to be obvious in the code.
>Since in Clojure we program with verbs, not 
> nouns,
>I think *documentation is best made by example*.
>4. Documentation of a Var should not be a formal description of what
>it is and what it does with some cryptically-named variables. *Every
>bit of documentation should be a micro-tutorial*. Emphasis should be
>put on usage, examples, tips, pitfalls, howtos.
>5. There should be structure in the documentation, and it shouldn't be
>just :see-also links - *there should be semantics* in it.  For
>example, some functions/macros are really meant to be nothing but
>shorthands for calling other functions : that kind of relationship should
>be explicitly documented.
>6. Documentation should not be just information about each separate
>Var in a namespace. There should be a hierarchy to make the most useful
>elements of an API more obvious. Also, adding cross-vars documentation
>elements such as tags and topics could make it easier to navigate and
>understand.
>7. *Documentation in the REPL is great*, it was one of the very good
>surprises when I started learning Clojure. However, a rich and good-looking
>presentation like in Javadocs would be welcome too.
>
> Of course, all of the above are just vague principles. Here is *some
> functionality I suggest for a start :*
>
>1. Documentation content elements could be written in a Clojure DSL
>emulating some kind of docbook-like markup language.
>2. On the user side, the documentation would be accessible through a
>generated web interface, a REPL interface, and maybe other formats like
>Wiki.
>3. Documentation could be programmed anywhere in a project by s