On Jan 21, 2013, at 12:20, Andy Fingerhut wrote:
> If one wanted *slightly* more editorial control of what appeared
> in those doc strings, they could publish a not-very-large file of
> "new improved doc strings" and make a macro like doc and cdoc that
> shows them. Or one could even redefine doc in your own REPL to
> show the new doc strings instead of the ones built into Clojure.
I've actually thought about doing something like this. True, there
is the slightly thorny issue of keeping the contributed docs up to
date, but Codeq could certainly tell us when any function (including
its doc string) has changed. That could be used to send a bluebird
to the documentation maintainers whenever an inspection is needed.
Decoupling documentation from the code would have multiple benefits:
* As discussed, it would allow changes to be made easily, quickly,
and by any interested party. Some sort of version management,
coupled with identity tracking for submitters, would keep most
of the noise under control.
* It would completely defuse any arguments about what information
should or shouldn't be included. Indeed, it would let us split
up the documentation into sections (eg, short/full description,
examples, related functions). This information would fit well
in a system like Codeq and could be displayed as desired.
* It would allow us to shift from "ASCII/monospace" formatting to
a more readable (and semantically meaningful) mixture of fonts,
layout directives, etc.
Something like Markdown (with Clojure-friendly sigils) could be
used to identify types of text, add formatting hints, etc. We
could then have a reader (xdoc?) that handled fonts nicely.
Note that a system such as Codeq could easily integrate information
from code quanta with relevant documentation from other sources. I
could also imagine Autodoc getting into this game. In summary, we
HAVE the technology (:-).
-r
--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume r...@cfcl.com
http://www.cfcl.com/rdm/weblog +1 650-873-7841
Software system design, development, and documentation
--
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
