Gregg Reynolds <d...@mobileink.com> writes:
> On Tue, May 6, 2014 at 10:11 AM, Phillip Lord
> <phillip.l...@newcastle.ac.uk>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 "</concept>" 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.
