On Jan 21, 2013, at 4:31 PM, Rich Morin wrote: > 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 (:-).
Yes, we do have the technology, and have for years now. The technology isn't the hard part in this case. The only barrier to entry is the willingness and ability to spend time, more time, and yet more time, where the benefit is mostly what you learn and the thanks you get, minus any complaints you get for not doing it the way the complainer wants you to (scratch that last part if you can ignore them). If that sounds like fun to you, I heartily recommend going for it! Just let me know when I can submit enhanced docstrings, and you can bet I will. Minor suggestions: If someone wants to use codeq for this, more power to them. However, having a separate set of "enhanced docstrings" for each released version of Clojure or library would probably be enough, and "diff" is sufficient to keep track of changes when things are relatively stable as they are within many libraries. I wouldn't say it would defuse any arguments about what information should or shouldn't be included. Any such arguments would move from the Clojure team to whoever maintains the enhanced docstrings. :-) One could imagine allowing multiple sets of such enhanced-docstrings to be distributed from multiple parties, and Clojure users could pick and choose which ones they prefer to look at. However, there is definitely an advantage to having one common source for such things. Andy -- 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
