Can doc and jdoc be refactored to a common protocol while it's still early?

Question

A fresh clojure library clojure.java.doc introduces some nice functions for querying javadoc.
It all seems nice and useful, I really can't complain (nor this is high priority to me since Javadoc is usually so verbose that I would probably continue to read it in the Web browser unless I discover use cases where REPL access is more practical to me).

However, one thing that struck my mind, and I had to ask is this: why introduce new functions, such as jdoc? Wouldn't it be more convenient to introduce a protocol (say, doc) which could then be extended to support
1. original Clojure doc
2. Javadoc
3. some sort of javascript doc, if that exists
4. C# doc
5. Native libraries doc, etc.

I understand that doc is a part of Clojure core, which you avoid changing at any costs, but this protocol wouldn't have to touch it.

It could simply be a "replacement" from the new namespace, which would have one implementation that invokes doc, but also be open to other implementations, such as jdoc.

And I understand that for Clojure core it's an absolute priority to not even change a formatting of the source code unless it's absolutely necessary, to keep very detailed compilation behavior or whatnot. It's a choice you made, it has its traidoffs, you chose those, and that's it. But, are those tradeoffs the same for namespaces such as clojure.repl and functions such as doc?

Answer 1

This library (which has not been released yet, and is still a work in progress) is focused right now on the narrow goal of reading Javadoc directly in the REPL. It's packaged as a library as a first pass. There are a variety of ways it might (or might not) be incorporated into core in the future - that is a question for later as we get feedback on the idea.

Because this library has a big dependency footprint, it's not something we would want to include in core directly, however it could potentially be incorporated via external tool invocation, much as we incorporate tools.deps classpath construction under add-lib using an external tool invocation with its own classpath.

Whether it could be incorporated into doc itself is a very open question. To date, we have simply extended the functionality inside doc (with specs for example) without making it an open system, but doing so is one interesting option available when we look at incorporation in the future.

Comments

I like the idea of a common protocol with backends for various documentation. clojure.java.doc could be used to implement it for Java.