Adding JavaDocs for Interoperability with Java?

[Timur]

Hi everyone,

Is it possible to add JavaDocs to Clojure so that it can support Java programmers. For instance a JavaDoc to a protocol or to an interface defined in Clojure which is later on read by a Java developer?

Regards,

Timur

[Plínio Balduino]

Hi, Timur

AFAIK, JavaDocs are just comments with some predefined tags that are completely ignored by Java compiler. As Clojure works directly with bytecode, I think it's not possible to insert any kind of JavaDoc in Clojure compiled interface or class. 

Regards

Plínio Balduino

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@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+u...@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+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Colin Fleming]

Hi Timur,

The problem with JavaDoc is that it's a source-level attribute, so in order to be used from a Java editor the editor would have to understand Clojure. This is actually possible in Cursive - as far as I'm aware no other system does this right now. The other aspect would be generating JavaDoc HTML when offline documentation is produced - I don't know if the javadoc tool is extensible in order to allow this.

However the bigger issue is that most of the elements exposed to Java don't support any documentation. definterface, gen-class, deftype & defrecord do not. defprotocol does, but the interface generated from the protocol is really an implementation detail, I don't think it's intended to be used for interop. Some new commenting convention would need to be developed.

For all these reasons, I generally recommend defining your interop interfaces in Java and just implementing them in Clojure.

Cheers,

Colin

--

[wpar...@yahoo.com]

A few other thoughts here:

- To elaborate on Colin's suggestion a bit, if you define Java interfaces in Java, it's easy to create a function that reifies those interfaces (this means that it returns an object that implements arbitrary interfaces).  In this case the only interop a consumer would need to worry about would be a call to a Clojure function that returns an instance of the relevant object.  Such a function would basically serve the role of a factory constructor.  Everything else would be plain Java from their point of view. https://clojuredocs.org/clojure.core/reify

- Apologies if it's too obvious, but Clojure does have a docs tool.  Obviously it wouldn't look the same as Javadocs, but it might fit your needs with a little elaboration in the docstrings on how to call them from Java. https://github.com/weavejester/codox

- If you really need Javadoc (corporate compliance reasons?), you could create a Java class that uses the Clojure Java API to call the Clojure functions and expose that class.  I personally prefer using gen-class with static methods that call the relevant Clojure functions, since manually writing a Java wrapper for Clojure functions gets a little tedious, but it does allow complete hiding of the Clojure code behind a Java wrapper. http://clojure.github.io/clojure/javadoc/clojure/java/api/package-summary.html

[Timur Sungur]

Thanks everyone for their helpful answers!

--

You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@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+u...@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 a topic in the Google Groups "Clojure" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/clojure/xCfrV3YhEsw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to clojure+u...@googlegroups.com.