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.

Reply via email to