Developer API docs

[Tal Liron]

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.