Clojurians Log v2

That's interesting! you may wanna share in #dev-tooling too

That sounds like a good thing to use in clojure-lsp, when user hover or ask for docs for current symbol! I suppose it works only for jdk or any other libs somehow?

It also supports retrieving information from jar sources as well.

oh cool, I don't see a example of that in docs, but sounds interesting

Probably worth calling out in the readme. I’ll update

if you are a tool creator and interested in this functionality, we are interested in hearing your feedback about how to make the lower levels of it useful to you

One of the major issues tooling has is java interop, at least in clojure-lsp / clj-kondo, actually I'm fixing one right now with borkdude https://clojurians.slack.com/archives/CPABC1H61/p1763467383675949 😂 So javadoc for sure may be a good addition

this is great. i know there's been some work to clean up doc in clojure core (clojure.repl?), so is this intended to be the alternative/better path to the built-in function?

I'm interested in integrating this. One thing that I'll need to figure out is given some source code near the cursor, how do I prioritize this source of documentation vs :doc metadata. I'm currently using https://github.com/alexander-yakushev/compliment, which allows custom sources for docs and completions.

@smith.adriane I believe clojure/java.doc is focused on java docstrings, not clojure code

right, but given some text near the cursor, you need to figure out which source to use. It's probably usually unambiguous, but there may be edge cases.

ah yeah, indeed, for clojure-lsp at least we already have this differentiation what is clojure and what is java from kondo analysis

particularly, namespaces with :gen-class

something that is gen-classed will not have either kind of documentation

Namespaces have doc strings.

how is that relevant?

will the docstring for clojure.java.javadoc be updated to recommend this library?

The main way I intend to use clojure/java.doc is as source for "show relevant documentation for code near the text editor cursor". I am now noticing that jdoc-data and sigs aren't functions that accept symbols, but are macros. For an editor that wants to present a doc string for the code under the cursor, is the recommended way to resolve a method and get the doc string to call eval? eg. given some source code as a string like "^[char/1] String/valueOf" , is there a recommended way to get the markdown or list of signatures?

Never rule out some grand unified doc strategy in the future but at the moment doc and clojure.java.javadoc will keep doing their thing. Some bits of clean up possibly coming to clojure.java.javadoc not withstanding. @nbtheduke

it's fun to see y'all release libraries for stuff that at one point might have been builtins. makes me hopeful for the future (more core libraries, fewer built-in namespaces)

jdoc-data and sigs are macros but they call through to public functions (`sigs-fn`, javadoc-data-fn) that accept strings in the api.clj ns. @smith.adriane

and classnames are resolved based on the value of *ns*?

Great tool ! Just report this as not working: (add-libs '{com.microsoft.onnxruntime/onnxruntime {:mvn-version "1.23.2"}}) (jdoc ai.onnxruntime.OrtSession/.run) No javadoc description available for this method. No javadoc description available for this method. No javadoc description available for this method. No javadoc description available for this method. No javadoc description available for this method. No javadoc description available for this method. No javadoc description available for this method. But I see javadoc here of the "run" method: https://onnxruntime.ai/docs/api/java/ai/onnxruntime/OrtSession.html

@nbtheduke re your questions above in relation to core - there are a variety of ways this project may evolve and we have not yet had a conversation with Rich about that. we thought it useful now and worthy of getting feedback in its current form. Because this project depends on a pile of libraries (both tools.deps to find and download javadoc jars, and then parsing/formatting stuff to read and translate the javadoc html), it's not suitable for direct inclusion in core. However, it could be included via external tool invocation (as we do with add-libs) - that could be done as an addition/modification to clojure.java.javadoc ns (which has similar but different goals), or possibly by widening doc into a more open system and connecting it with that system. TBD on all of that.

@smith.adriane you should use doc etc to get namespace doc strings. This tool is focused on javadoc for classes and methods. genclass'ed classes will be classes without javadoc and thus this tool will not be relevant. if the genclass'ed class implements interfaces, those are likely the more relevant place to look for documentation (same with reify / defrecord + deftype classes).

Yeah I don't want or need this in clojure core, more wondering if (like clojure.xml -> clojure.data.xml) this is more of a "library supersedes outdated built-in" scenario and if it would be helpful to make such a note in the docstrings of the core namespaces

@carsten.behring Thanks for the report. I believe there is an enhancement needed for arg parsing to accommodate this particular situation. Stay tuned.

clojure.java.javadoc model: find a public HTML javadoc URL (for small set of hardcoded URLs) some HTML javadoc, then view it in external HTML viewer clojure.java.doc model: download the HTML javadoc from a Maven repo (precise info known via basis), then translate it and view it in REPL these obviously overlap in class->html API and suggest it might be possible to bring these into alignment. we have tickets ready to update clojure.java.javadoc for the expected JVM bump in Clojure 1.13 and deprecating some of the existing long-broken ideas like googling for javadoc.

if we can get to "don't make me add-lib and require to use it" either via jdoc or even existing doc, that would be pretty sweet imo

TBH I believe this should be lying in tools like LSP, so clojure-lsp can get symbol and use clojure.java.javadoc under the hood and present, like we do for https://clojure-lsp.io/features/#documentation-and-clojuredocs-integration

possibly, I'm very interested in seeing what IDE level tools do with it (since they can hide the add-lib / require parts). I also don't know if the original html is actually better for those kinds of tools if they have html viewers - in that case the class->html part of the API is the more relevant bit

or maybe it's all irrelevant if the IDE already has some class->html viewer feature, dunno

exactly, agree, and IDEs have the markdown support for those things, so the most important part is the string content, the rest is UI

sigs is probably independently useful (and actually doesn't really depend on anything javadoc related - we could really add that independently)

New version v0.1.2 released that fixes the issue reported by @carsten.behring