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 philli...@newcastle.ac.uk
javascript: 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
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
I added some stuff on the Elisp documentation. Others can update if they
think I am wrong!
Phil
Val Waeselynck val.vval...@gmail.com 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,
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
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
Here
:https://docs.google.com/spreadsheets/d/1HyS9qstgEqmdv0MtDm3xEsImnDjCYQhar1PQP3fzwMc/edit?usp=sharingI
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
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
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
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
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
Sean Corfield s...@corfield.org writes:
On May 6, 2014, at 8:11 AM, Phillip Lord phillip.l...@newcastle.ac.uk 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
Tim Daly d...@axiom-developer.org 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
Gregg Reynolds d...@mobileink.com writes:
On Tue, May 6, 2014 at 10:11 AM, Phillip Lord
phillip.l...@newcastle.ac.ukwrote:
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
Gregg Reynolds d...@mobileink.com 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
On Tue, May 6, 2014 at 4:53 AM, Phillip Lord
phillip.l...@newcastle.ac.ukwrote:
Gregg Reynolds d...@mobileink.com 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
On Tuesday, May 6, 2014 4:53:36 AM UTC-5, Phillip Lord wrote:
Gregg Reynolds d...@mobileink.com javascript: 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
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
Gregg Reynolds d...@mobileink.com 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
Mars0i marsh...@logical.net 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:
On Tue, May 6, 2014 at 10:11 AM, Phillip Lord
phillip.l...@newcastle.ac.ukwrote:
Gregg Reynolds d...@mobileink.com 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.
On Sat, May 3, 2014 at 3:46 PM, Val Waeselynck val.vval...@gmail.comwrote:
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,
On May 6, 2014, at 8:11 AM, Phillip Lord phillip.l...@newcastle.ac.uk 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
On Tue, May 6, 2014 at 9:56 AM, Sean Corfield s...@corfield.org 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.
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.
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
On Tuesday, May 6, 2014 1:41:25 PM UTC-4, puzzler wrote:
On Tue, May 6, 2014 at 9:56 AM, Sean Corfield se...@corfield.orgjavascript:
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
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] -
On May 6, 2014, at 10:41 AM, Mark Engelberg mark.engelb...@gmail.com 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/
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
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
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
On Tue, May 6, 2014 at 2:22 PM, Tim Daly d...@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
Clojure is being reworked into literate form already
Proof of this claim?
On Tue, May 6, 2014 at 7:32 PM, Gregg Reynolds d...@mobileink.com wrote:
On Tue, May 6, 2014 at 2:22 PM, Tim Daly d...@axiom-developer.org wrote:
Gregg,
My original comment on litprog (bad bad bad) was
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
(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
On Mon, May 5, 2014 at 9:32 AM, Mars0i marsh...@logical.net 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
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 :
-
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,
On Thu, May 1, 2014 at 9:49 PM, Sean Corfield s...@corfield.org wrote:
On Apr 30, 2014, at 4:08 PM, Val Waeselynck val.vval...@gmail.com 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
On Fri, May 2, 2014 at 4:00 AM, Val Waeselynck val.vval...@gmail.comwrote:
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
Sean Corfield s...@corfield.org 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
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,
(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.
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
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
On Apr 30, 2014, at 4:08 PM, Val Waeselynck val.vval...@gmail.com 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
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
Phil Hagelberg p...@hagelb.org 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
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
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
On Tue, Apr 29, 2014 at 7:44 PM, Phil Hagelberg p...@hagelb.org 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
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
On Apr 30, 2014, at 11:03 AM, Gregg Reynolds d...@mobileink.com 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
On Apr 29, 2014, at 9:42 PM, Atamert Ölçgen mu...@muhuk.com 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
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
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
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,
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
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,
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
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
On Wed, Apr 30, 2014 at 4:18 AM, Phil Hagelberg p...@hagelb.org 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,
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
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
I'm all for getting behind Marginalia and improving it to meet whatever needs
are wanted by the community while staying true to it's docco roots.
--
You received this message because you are subscribed to the Google
Groups Clojure group.
To post to this group, send email to
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
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
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,
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
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
70 matches
Mail list logo
