Alex, glad to see we're on the same wavelength about this more or less.
Christopher, some other deliverables worth considering:
- What format is documentation in? As Grimoire is evidence, plain doc
text is pretty badly formatted on average certainly in comparison to
HTML or even markdown. It'd be awesome if we had a convention for
non-plain text documentation and for indicating format to
documentation tools accordingly.
- Notes. Alex mentioned "extended documentation". Clojure has often
been criticized for having "excessively short" docstrings. While I
agree that a few well chosen words typically do better than many
words, there are cases such as the documentation for defmulti where
more than just what passes for the docstring is required. defmulti
for instance is just one entry point to the subject of multimethods
which while documented well on clojure.org is given sufficient
general treatment in no "docstrings". Andy F has Thalia, a
project which modifies docstrings in place to try and augment some
of the docs which are considered most .. terse. It seems that Alex
wants whatever format this project produces to support arbitrarily
many "additional" docstrings for a given entity. One arguable defect
of the Grimoire representation as it stands is that I implicitly
limited myself to a single "note" (user docstring/extension) per
entity.
- Examples. Most frequently, example code is presented as REPL
sessions. Again, there is no common format for these. Some "examples"
include the prompt string. Others don't. Some include STDOUT and
STDERR inline with returned results. Others comment it out.
It'd be awesome if we had tooling (including a common format or
format indicator) for representing examples. Right now Grimoire and
ClojureDocs use plain text which defeats all analysis and linking
efforts. Honestly a nREPL session replay could probably be
sufficient, but this is a research question. How you deal with deps
to run an example is a related question.
It'd be awesome for instance if I could share examples with the
4clojure folks or with Devn Walters' project getclojure.
- Links. I previously played with a representation which I called
"var-link" for uniquely naming any of
[group artifact version platform ns def].
The idea was that you could write a URI of the form
ns:org.clojure/clojure/1.6.0/clojure.core or
def:org.clojure/clojure/1.6.0/clojure.core/concat etc.
This idea predates the existing grimoire.things namespace, and was
abandoned in favor of it since grimoire.things does almost this job.
However grimoire.things fails entirely to provide or read any
reasonable URI or other structured text representation for Things.
It'd be great if we had a standard representation as such, so that
documentation writers could explicitly link to other entities from
docstrings. Again this goes back to the docstring formatting goal.
What if I could explicitly link to say nth from first and second's
docs? Link to defmethod and prefer-method from defmulti's docs?
I think you get the idea.
Just some ideas that've been rattling around in my head unimplemented.
Reid
--
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.
