Hey Christopher, I'm Reid, the Grimoire maintainer. I'm delighted to see that someone besides myself and Alex is interested in this project and I wish you the best in your GSoC application.
I'm somewhat concerned in reading your proposal that while you claim the proposed data structure represents a "minimal superset of the other documentation engines", it is by no means a superset of the lib-grimoire infrastructure. In fact the proposed "list of defs, list of namespaces" fails entirely to address the issues with multiple versions of multiple artifacts on multiple platforms that I've spent the last four releases of Grimoire and lib-grimoire wrangling. The Thing structure and list/walk/read/write API I've provided via lib-grimoire seem to solve these issues at least in my work of trying to build a general documentation engine behind Grimoire so that I can just add artifacts left and right. If I wanted to build a system like Grimoire where the fundamental navigation is entirely `group -> artifact -> version -> platform -> ns -> def` hierarchical decent, why would I choose your representation over the representation already present and usable in lib-grimoire? I note with some entertainment that there exists a set of namespaces duplicated between ClojureScript's Clojure and ClojureScript sources. For these namespaces and the defs therein, CrossClj.info incorrectly displays the Clojure namespaces when doing a qualified symbol lookup. Grimoire used to have the same issue until I asked David Nolen and he said that's a bug. You absolutely need the platform to disambiguate what definition and source you're looking at. If I wanted to display the documentation for all the forks of `org.clojure/clojure`, how could I get all of that into your system? All the forks have defs in the namespace `clojure.core`. How do you propose to tell them apart? You have to have the Maven artifactid and groupid. Multiple versions of a single artifact? Now you need the Maven version as well. Now we've encoded all the same information that lib-grimoire already does. Why would I agree to use this pair of lists structure and then reconstruct a hierarchy from node data when I could use a fundamentally hierarchical structure for instance the one proposed [here](https://github.com/clojure-grimoire/lib-grimoire/issues/9)? [by my metrics](http://conj.io/heatmap), the most-visited URLs on Grimoire specify a single def or other content precisely. Why would I want to adopt a data format which does not inherently represent this common case of documentation being a lookup when as above I could build or use one that does? That you discard these datums with no discussion is worrysome to say the least since I found that they were needed and was forced to invent them after I had done without them for some time. I agree that there is a lot of duplicated code between the various documentation systems. Most of it has to do with finding namespaces on the classpath, loading them and documenting them. Thankfully we already have `clojure.tools.namespace` which is supposed to solve this problem. Currently `clojure.tools.namespace` can't find ClojureScript namespaces. As I recall, codox ducks this limitation by implementing its own classpath searching code. (apologies to Stuart Sierra who I bugged about patching this a while back.) Your goal of "Building a repl plugin that will search statically across the code accessible by the project so you can query all artifacts without actually loading them." could use some clarification. It took me longer than I care to admit to realize you were talking about browsing _documentation_ via some packaged documentation structure(s) before the user actually loads code. Since the novel work you propose is really a documentation distribution convention, you should say more about that. Are you suggesting that every artifact package a "doc.edn" file? Is this an open research question you don't have an answer to yet? This is a set of problems I've sunk a lot of time into and would like to see addressed. It is certainly not my intent to dissuade you from this project. Whatever documentation packaging and distribution system you come up with I'm likely to wind up supporting in Grimoire so it's in my direct interests to make sure that you skip as many of the pitfalls that I hit as possible. I hope that you find this feedback constructive, and I look forwards to seeing how this project evolves. Feel free to bug me about Grimoire related stuff, especially if you find bugs or documentation issues :P All the best, 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.
