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 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. > If it were genuinely failing us in some important way, it would be > changed. This is, I think, a variant of the no true Scotsman fallacy. You can say, about any complaint about documentation system are wrong, because if they were right, it would be changed. By definition I can produce no counter examples. 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.
