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