From jonathan.gibbons at oracle.com  Mon Aug 19 19:23:19 2013
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 19 Aug 2013 19:23:19 -0700
Subject: Enum.valueOf(String)
Message-ID: <5212D317.4030905@oracle.com>

> ------------------------------------------------------------------------
> I noticed this method is not listed in the Javadocs for 5/6/7/8 but it's
> part of every enum. Is this an oversight or is there a good reason why it's
> not documented?
>
> -- 
> Cheers,
> Paul

Paul,

Can you give more details?

On a sample size of one, I see the method descriptions being generated 
correctly

http://docs.oracle.com/javase/7/docs/api/javax/lang/model/SourceVersion.html

http://docs.oracle.com/javase/7/docs/api/javax/lang/model/SourceVersion.html#valueOf%28java.lang.String%29
http://docs.oracle.com/javase/7/docs/api/javax/lang/model/SourceVersion.html#values%28%29

-- Jon
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130819/fa051b66/attachment.html 

From shogun70 at gmail.com  Sun Aug 25 13:59:08 2013
From: shogun70 at gmail.com (Sean Hogan)
Date: Mon, 26 Aug 2013 06:59:08 +1000
Subject: next gen javadoc (javadoc without frameset)
Message-ID: <CAHQTpmCQjXkDeAOdnoGnbf3J_Jj=qbX2FgTMqQ0vpdAEK_x+AA@mail.gmail.com>

## Framesets are simple, useful, familiar ##

Javadoc relies on HTML's <frameset> for it's "FRAMES" view of doc sets.
This feature adds some convenient navigation whilst Javadoc's HTML output
remains as-simple-as-possible. It is familiar and useful and you wouldn't
abandon it unless an alternative was unquestionably better and just as
simple.


## Framesets don't really fit on the web ##

There is however, a weakness of <frameset> based sites - the URL in the
address bar doesn't match the primary content being viewed. As a
consequence:

- navigating a hyperlink or via back and forwards button doesn't update the
URL in the address bar, which is unexpected behavior (although not to those
familiar with javadoc)

- search engines will link to the primary content page, so users will
arrive at the NOFRAMES view and need to manually choose the FRAMES view.

- users can't bookmark pages or email the URL when in the FRAMES view


## With AJAX and pushState, framesets can be emulated / surpassed ##

Fortunately, all up-to-date browsers have the `history.pushState()` API
call which allows javascript to update the URL in address bar without
reloading the page. This - together with the long-supported XMLHttpRequest
- should allow a Javascript-driven **emulation** of framesets that also
keeps the URL in the address bar valid.

(Naturally it is not necessary to strictly emulate the current UI if
something better is possible, e.g. a dynamic search box.)


## A frameset replacement must be (mostly) decoupled from Javadoc ##

For this approach to be a viable replacement for framesets it must be
possible to implement it with minimal change to javadoc's HTML output.
Ideally this change would be a single <script src="boot.js"> in every page
to bootstrap the enhanced UI.

If this can be achieved then the UI can be updated independently of javadoc
being run. This would make UI customization / rebranding / fixes /
enhancement quicker and simpler.


## An implementation ##

The good news is that this approach already has an implementation.

The javadoc-panner project brings pushState-assisted-navigation and a
customizable UI to documentation-sets generated by Javadoc-1.7. There is a
public project page at https://github.com/meekostuff/javadoc-panner


### Proof of concept

These enhancements **are** achieved with a single bootstrap script.
Currently this is the most important feature of javadoc-panner.


### Demonstrations

The generic method of applying javadoc-panner to a doc-set is with a
javascript bookmarklet. This can be most easily installed from
http://devel.meekostuff.net/javadoc-panner/0.1-devel/

There is also an introduction video with a few thoughts, a walk-through on
how to install the bookmarklet, and a short demo of it running on a few
sites. See http://youtu.be/LC45G7zsCFs


### The UI can be easily updated

When you try out javadoc-panner or watch the demo, the most important thing
to remember is that *you don't have to like the UI* because **it can be
updated independently**. Another important thing to note is that the UI is
implemented as a standalone HTML document - another feature that should
make UI evolution quicker and simpler.


### Easily integrated

It is also possible (though undocumented) to integrate javadoc-panner into
an already generated doc-set. You can see this in action at

http://playground.meekostuff.net/javadoc/jdk8/docs/jdk/api/jpda/jdi/overview-summary.html

This doc-set is copied from the one at

http://download.java.net/jdk8/docs/jdk/api/jpda/jdi/overview-summary.html

The only difference between the HTML source files and the files in this
doc-set
is that each file is prepended with the lines:

    <!DOCTYPE html>
    <script src="/javadoc/boot.js"></script>


## Feedback required ##

It would be great to have feedback.

Any questions or comments on the approach outlined here are welcome.

If there are other news groups where it would be appropriate to discuss
this then please notify me.

Issues / bugs / feature-requests for the javadoc-panner project are best
directed to the project issues page
    https://github.com/meekostuff/javadoc-panner/issues

regards,
Sean Hogan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130826/6fb0ef27/attachment.html 

From shogun70 at gmail.com  Tue Aug 27 16:35:17 2013
From: shogun70 at gmail.com (Sean Hogan)
Date: Wed, 28 Aug 2013 09:35:17 +1000
Subject: next gen javadoc (javadoc without framesets)
Message-ID: <CAHQTpmCHUD1Z5ce8ZYMP8i92CjP1axkJXSp2xqK=OMbfKvSAaA@mail.gmail.com>

Thanks to people who have tried out javadoc-panner - either the bookmarklet
or the integrated javadoc-set at:

http://playground.meekostuff.net/javadoc/jdk8/docs/jdk/api/jpda/jdi/overview-summary.html

I should have explained that there is only this one modified javadoc set on
the site. If you have been viewing this set and followed a hyperlink to an
external page then you would have seen a permanent waiting-spinner (or
perhaps something unpredictable). This should be fixed now - **external
hyperlinks will only lead to an error page**.

I have also identified a couple of (hopefully rare) timing problems which
should be worked-around in a day or two. Issues can be reported and
followed at the public project page:
    https://github.com/meekostuff/javadoc-panner/issues

regards,
Sean Hogan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130828/2dfd1c73/attachment.html