On Tue, May 6, 2014 at 10:11 AM, Phillip Lord <phillip.l...@newcastle.ac.uk>wrote:
> 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 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<http://clojure.github.io/clojure/clojure.core-api.html#clojure.core/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 <https://github.com/mobileink/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 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. > 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. > 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. -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.
