Developer API docs

[Attila Szegedi]

The internal API is indeed documented in source, that’s just a good practice for future code comprehension and maintenance. But those APIs are not intended to be relied upon externally, as we don’t want to burden ourselves with backwards compatibility requirements over them. Lots of methods are public because of internal cross-package references. Note also that with the advent of modules in Java 9, we’ll have a better control of externally accessible APIs and you will indeed be entirely prevented from accessing what we don’t want to expose.

What APIs are you using, BTW? Just curious if I can suggest an alternative approach, or even consider if something you use should be publicly supported.

A special case is the documentation for e.g. NativeJava methods, which are implementations of the global Java object. We publish these two additional documents:

<http://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/javascript.html <http://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/javascript.html>>
<https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/nashorn/api.html <https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/nashorn/api.html>>

Attila.


> On Jul 6, 2015, at 8:01 AM, Tal Liron <tal.liron at threecrickets.com> wrote:
> 
> Sundar,
> 
> The JDK9 page is not loading for me.
> 
> I am talking about JavaDocs: documentation for the Java API. Lots of the internal API is documented in source, but it's not generated and hosted publicly anywhere right now. I don't mean private classes: there is a wide range of public classes that do not have publicly-hosted documentation.
> 
> I understand the "internal" issue from your perspective, but I hope you also understand that many projects need access to these internals to do good things with Nashorn. Yes, we know things might change, but that's true for any dependency. You support certain versions and will need to work on updates.
> 
> An example of two such projects are my MongoDB driver for Nashorn and extensible JSON codec for Nashorn:
> 
> https://github.com/tliron/mongodb-jvm
> https://github.com/tliron/json-jvm
> 
> These two projects cannot achieve their goals without access to Nashorn's (and Rhino's, and Groovy's, and Clojure's, etc.) internals. I would like to host my JavaDocs publicly, but right now all links to Nashorn types cannot be resolved. Developers can, however, look at the source code and read the documentation there. It's just awkward.
> 
> On 07/05/2015 11:20 PM, A. Sundararajan wrote:
>> Hi,
>> 
>> https://docs.oracle.com/javase/8/docs/jdk/api/nashorn/
>> 
>> Actually, those are the only committed "official" APIs. For jdk9, jdk.nashorn.api.tree.* is added.
>> 
>> http://download.java.net/jdk9/docs/jdk/api/nashorn/
>> 
>> Anything else is considered 'internal' implementation detail - and so subject to change anytime without any notice. If you need docs for the current snapshot of the nashorn project, you can do "ant javadoc" locally in your nashorn clone.
>> 
>> Keeping latest javadoc somewhere in sync. with the repo would be hard. Also, it is very likely that people will take this as "published" API and demand backward compatibility (which is hard to support).
>> 
>> PS. Or are you talking about docs for JavaScript functions, constructors? We need to do something for the JS docs still...
>> 
>> Thanks,
>> -Sundar
>> 
>> On Sunday 05 July 2015 02:10 AM, Tal Liron wrote:
>>> Hi Nashorn,
>>> 
>>> The only available JavaDocs I found are those for approved public consumption:
>>> 
>>> https://docs.oracle.com/javase/8/docs/jdk/api/nashorn/
>>> 
>>> But, as you know, quite a few projects need to dig deeper into Nashorn plumbing. Would you consider publishing latest-official-release versions of the *complete* JavaDocs somewhere? It would be helpful if I could link my public JavaDocs to yours.