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

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

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

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 / contribu

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

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 reStructu

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

> > 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 document

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

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 bec

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

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 compl

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

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

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

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 i

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

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

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

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-structur

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

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" b

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

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

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

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 Re

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

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 w

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

>> 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 thi

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

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

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

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

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

> 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 docum

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

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 expl

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

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

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

> 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

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

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 th

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

> 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

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

> 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;

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

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 ju

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

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, d

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

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 pri

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

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 document

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

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: >> - tra

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

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 a

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

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 d

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

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

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

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 a

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

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

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

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 fig

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

(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 "

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

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 : - encouragi

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

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 d

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

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

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

> 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 >

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

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 abo

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

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

Re: Proposing a new Clojure documentation system (in 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 doe

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

(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.

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

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 > typ

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

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.

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

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

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

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 documenta

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

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 larges

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

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,

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

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 relativ

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

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 impo

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

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 lik

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

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 >

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

> 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 file

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

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

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

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

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

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

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

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 eno

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

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

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

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

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

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

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

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

Proposing a new Clojure documentation system (in Clojure)

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 clojure@googlegroup

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

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 centrep

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

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

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

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 sa

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

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, pu

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

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 re

Proposing a new Clojure documentation system (in Clojure)

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 l