Bug 22805

Tim, may we know what was your usage pattern of the JavaDoc tab ? I
thought that the javadoc structure is so weird so it is only rarely
explored by the user.
Or do you use only the index files as starting points for browsing
throught the docs ?

I agree, browsing Javadoc is not so useful or fun.  My entry point was
always the index files.  Usually I would add them to the project tab
(and then rename the shadows to identify them). 

The problem for me is that, usually I want to keep open the JDK docs
or OpenAPI docs, depending on what I'm doing, and short of picking a
random class and fetching its Javadoc, I can't do that now.  

So I don't care about browsing so much as having access to the index
file.

Tim, you can access mounted javadoc from Explorer/Filesystems tab.
Javadoc filesystems are mounted as hidden.

Yes, I know you can do that - that's what I did.  But my point is that
if you mount Javadoc using the Javadoc manager, there is now no UI to
access the index page for that Javadoc.

Consider the NetBeans APIs Javadoc set - most of the important stuff
is not the class Javadoc itself.  Should the workflow for this be

 - Mount Javadoc with manager
 - Press CTRL-F1 on random class from APIs (and if I have never 
   written a module and don't know what classes are in the APIs,
   how do I know what to type?)
 - Click Overview at the top of the page

just to get to the index page of the Javadoc?

There could be a Help menu item that finds the index files and puts
them in a submenu, or something, but there needs to be a way in
the standard user interface to get at the Javadoc.

mick.jordan@eng.sun.com suggested something like this to me long ago.
I fully agree. The current UI is not enough.

Tim - View | Javadoc Index Search.

Here is a thought. Keep the search window mostly as it is now. In
addition to the Find button, add an Overviews button. If you open View
| J.I.S., you will initially see overviews rather than an empty list.
If you use the shortcut from the editor, it will of course immediately
try to find that class and show it instead.

There should be zero or one overview per mounted Javadoc filesystem.
If a file overview-summary.html is present in the root dir of the
filesystem (or api/ subdir I guess), an item for it will be displayed
in the list: either the display name of the filesystem, or the HTML
title of the page, or perhaps the HTML title of the page if distinct
from the Javadoc default and otherwise the display name of the filesystem.

Anyway, clicking the list item would of course browse you to
overview-summary.html: this is the main page of a Javadoc set, in no
frames mode, since frames are mostly useful for finding classes and
packages which is better handled by the J.I.S. window itself.

Changed to enhancement.It is not a bug form my point of view.

*** Issue 24555 has been marked as a duplicate of this issue. ***

I'd like to add my comment to this issue too. Don't know where exactly
to start...

as you could see I filled a P2 bug (marked as duplicate already) about
missing "javadoc" TAB in the Explorer.
I found it as a REGRESION 3 days ago and almost I thought it is P1 bug.

Now, you think I'm crazy alien, but I realy discovered it 3 days ago,
and just because of other IDE windows bug (almost all ide windows had
after import project CTL_*{title}) which had been breaking my
automatical tests. So I decide to delete my
$userdir/.../project/../windows dir, which after that forgot all
windows settings.
And then I recognized that the Explorer window NOW HAS right title,
but misses "javadoc" TAB which I was very used to use it. AND now
I can't:-((( grr...

I'm not fan of reading all long discusion on @netbeans.org mailing
list especialy on nbui@, and as I see know I miss it:-(((

So, what should I do now for to have it "javadoc" TAB back?
Open a discussion on nbui@ (I dislike this)...

till now, I'm at least increasing the priority and saying it's not
enhancement 'cause as I see it, it is pure REGRESION:
 There was an UI for that, but now disappeared

and as a REGRESSION is defined: it is when something was working
and suddenly  it stops work...
So if you wish replace one GUI with another do it in one step, not
just dismiss it and if someone requere it, don't say it is Enhancement....

thanks 

I can't agree with the P2/DEFECT categorization. The UI change was
discussed on nbui and accepted. There is no functionality missing, it
is simply displayed differently now. Would suggest restoring P3/ENH
status.

Well, each of us might be right if you look at it from his point of view:
 *you're right because you've been involved on nbui@ duscusion, so you
   see it as something like a progress. And now, you're taking current 
   design as a start point. In this case it is enhancement.
 *but I think I'm right too even though I don't watch nbui@ mailing
   list.
  (Question is if you could say about it that it's my misstake
   and I HAVE to watch to have right to later say that is bug. Or if
   it is only suggested to avoid this case of situation).
   So, as I told. I used my usersettings from the NetBeans version 
   3.0 or something like that. In a few days ago I still used them.
   And everything was all right (at least with that TAB). So I could
   not have any intention to watch nbui@, also I hadn't had any need
   to watch it. But Because of ANOTHER BUG in IDE(in windows system)
   I had to DELETE ONLY "window" dir in my:
   .../$userdir/system/Projects/$projname/.../windows
   and for me it is REGRESION which is clasified as P1 bug.
   
My point of view is based on that as a long-term user of NB ide
I was used to some comfort for more than 2 or 3 years!
And if Projects or whole ide can't hold compatible line with previous
thing and from one day to another(because of some stupid silly bug I
had to delete part of my settings) something disappeared because
someone discused it (Say me frankly how many "outside" Sun people were
involved in it) and thought it is right for new users 
and didn't think about old users, that is a bug, sorry:-(

We could do compromise to say it is P3/bug . But fix is easy to add
them back javadoc TAB, so it'll take only a few minutes for a
developer to add it back, P3 will only posspone this fix....

So... would it be sufficient to mark javadoc filesystems as visible
when upgrading from < 3.4 settings ? This way they will appear in the
main explorer, along with the other filesystems when the user runs 3.4
on < 3.4 settings.

Yes, I think in this way the ide behaves... I dind't try to import old
 settings 'cause I'm using continuesly one settings from version to
version from build to build....

The reason why I deleted part of say  <3.4 settings ".../windows" dir was:
 bad title of a few windows starting with "CTL_". (there are already
several CTL_ bugs on separate windows, but I should more probably fire
one general bug about it).

My CTL_Explorer title couldn't be reached by my automatical test....so
 I rather deleted windows settings (I have them backuped of course,
but it won't help me in my case I'm affraid)
Some kinda hack will help me  in userdir settings for xml file what I
should write in it to display that node...

I suggest more to add an ("Global")Option for explorer which TABs I
could see. By default of'course if it was discused and agreed should
be invisible.

-------------------
Now,the paragraf above confirmed me in about this issue that it is bug
in design. The new JavaDoc Manager, invisible javadoc" TAB and
other related stuffs are kind of new feature.
And there was forgoten about this usercases for which javadoc TAB
served and for which Tim and me complain about. Simply there
disapeared GUI for handling javdosc fs, and noone design the new one.
Till the time it will be done javadoc TAB should be bring up back.

realy thanks in advance

After discussion with Dan Mladek I decided to revert it to the
RFE(P3). There is possibility to create new action which will invoke
explorer window with javadoc folder which could be docked into main
explorer. But that is RFE.

My apologies - I did not notice that now you cannot even browse
index.html files from the Javadoc Manager dialog, which initially you
could. So that makes them less accessible indeed.

I still suggest having browsing functionality added to the Javadoc
Index Search dialog, as per my comment of May 1.

Created attachment 6218 [details]
Trivial module JAR to show Javadoc node in Runtime tab

The attached micromodule displays the old Javadoc node underneath the
Runtime tab. Restoring it to its own Explorer tab would also be
possible though a bit more work; see issue #20517 for details.

Great Jesse !!!
you've done exactly what we need. The functionality came back and its
UI fits new proposal;-)

(I didn't care how this functionality will look and where to find it,
just only to have it. NOW The node in Runtime TAB is probably
more suitable than it old javadoc TAB was:-)

thanks Jesse

Jesse's patch helps us, but only if it actually shows up in production
code.  What does a normal user of the IDE do?  They will not know
about the bug or the patch - they just won't be able to find the
Javadoc.  And the Runtime node is an available place to show it,
but what does Javadoc have to do with Runtime?  In terms of the user
model, it's not the right place.  Thanks, though, Jesse.

Please consider some variation on
http://www.netbeans.org/issues/show_bug.cgi?id=17362
as a proper solution to this issue.  Another option is a 
Javadoc submenu on the Help menu, with Actions that contain the
parsed titles from the indexes of all Javadoc.  This would not
be a terribly hard thing.

And what about create a new property "Show Javadoc tab in Explorer" in
Tools | Options | Code Documentation | Documentation? Default value
could be false. Is it acceptable?

Of course this is just a demo so we can actually try out proposed
solutions.

I like Tim's idea of a menu item. Moving it to the View menu for
consistency. Try the new version of the module.

Created attachment 6230 [details]
New module JAR: also adds an item to View menu

Created attachment 6232 [details]
Variant of 2nd JAR showing Javadoc node in Options window rather than Runtime tab

I would suggest making the following changes to the Javadoc Manager:

1. Include a "Browse" command button that opens the selected
   Javadoc in the web browser as if you'd navigated to it in
   the Explorer tree and chosen the index file.

   I think this would handle most users' requirements and would
   hide the "mounting" concept and prevent any need to navigate
   through an obtuse Javadoc directory structure.

2. Include a editable column in the grid for "Description"
   that matches the text in the Options dialog under...
       System - Filesystems Settings - Javadoc documentation

   Note: Currently adding Javadoc from the Javadoc Manager
         does not add an entry under the "Javadoc
         documentation" branch of the Options dialog.
         Instead, it is simply included ungrouped at the
         bottom of the "Filesystems Settings" node. A bug?

What do you think?

Re. note in #2 - actually not a bug, though behavior is probably
counterintuitive. "Javadoc Documentation" node currently holds
subnodes for various Javadoc-related settings, but *not* Javadoc
mounts. "Javadoc" subnode of Filesystems Settings is where Javadoc
mounts *supplied by modules* are conventionally placed, but
*user-initiated* mounts will just go directly beneath Filesystems
Settings (as far as I know). The old Javadoc Explorer tab root node
displayed all Javadoc mounts, whatever their origin, and so did not
correspond exactly to what you see underneath Filesystems Settings. 

Try my demo module which puts this old root node inside the catch-all
node in the Settings dialog. (Known problem with this demo: context
menus do not work on that node.)

The UI for Javadoc mounts sounds like a bit of a mess and needs a bit
of consolidation.

I don't see why they're not kept in the same place in the Options
dialog - maybe sub-grouped if some are supplied my modules (and
therefore read-only).

Jesse, I will try your module though in the next few days.

Thanks.

BTW: apisupport installs a menu item (nbfs: protocol *.url) to the
Help menu called "Local Open APIs Documentation" pointing to its own
documentation index. I did this long ago, since even with the old
Javadoc tab, it was a bit clumsy to open the index page, and the
summary page in this case is rather important since it links to much
of the actual documentation, not just generated Javadoc.

I have created a refined version of the helper module, and checked it
in as contrib/javadochelper/ in CVS.

http://contrib.netbeans.org/servlets/ProjectDownloadList

has a prebuilt NBM to try. Install it and check the View menu.

Patrick - this item is already mentioned in release notes. You may
want to link to this bug report and mention briefly that anyone who
finds the change really annoying can try this unsupported module for
relief.

Robert - could you add this module to the Alpha Update Center for
NetBeans 3.4? The NBM is already built and signed and should be ready
to use as is. See the contrib site for download.

I've published the module javadochelper on the Alpha Update Center
for Netbeans 3.4.

info added to release notes. Will commit in a few hours.

Seems as this feature is requested very often.

Is there any reason integrating Jesse's module with the Javadoc module
can't be scheduled for 4.0?  It should be a trivial amount of work to
do this.  Someone from UI should review, I guess, and decide if the
location of the menu is right.

It will probably need a minor tweak - not showing filesystem contents
in Tools | Options. It seems inconsistent there.

I guess the filesystem contents could be hidden in the subnode in
Options, but it seemed potentially useful there - a quick place to see
contents of mounted Javadoc FSs without having to mark them unhidden
first. Not terribly important either way, I think. There is not a
definite need for that node in Options, since everything settable is
visible somewhere in Options (under Documentation Settings or under
Filesystems Settings), and Javadoc Manager already provides a UI for
most interesting aspects. The View menu item is the important part of
the module.

BTW a couple missing things in the module:

- I18N of action (should be straightforward).

- Sanity-check on Japanese Javadoc mounts (try w/ JDK docs translation
as an example).

- I set it to filter out " - Overview" at the end of titles, as this
is commonly generated by Javadoc and adds no useful information to the
menu item. Should also filter out "Overview (" ... ")", for example
see JDK 1.4 docs which currently appear as "Overview (Java 2 Platform
SE v1.4.0)" whereas just "Java 2 Platform SE v1.4.0" would be more
readable.

- Also may need to create corresponding filters for Japanese. *Don't*
find the filter based on current locale, as a Japanese user may be
viewing both English and Japanese docs. Ideally the title filter would
be an aspect of the Javadoc search type rather than hardcoded into the
index view action. You could make it a user-editable regexp, but I
think it would be quite sufficient to hardcode the patterns into the
search type, as they are unlikely to need to be changed.

I would be willing to create a complete patch for the Javadoc module
if you want.

I have already I18Ned a little, thanks a lot for reminder about
localization issues. I will patch the search types on Monday.

May I propose something else ?
If I go to tools and then JavaDoc Manager, I can see a 
list of all Javadoc Installed.

Why not transform the content of the first column into a 
link to the main index page of that JavaDoc.
I think it's a beautifull and proper solution.

What do you think about ?

Hi Vincent,

I'm not sure if I understand your idea well, but I wish to have easy
possibility to (browse)explore javadoc FS as other types of FS, you know.
I want somewhere (easy access) node to all my javadoc FSs and their
files in them and without doing any exercises/tricks (unhide,etc.).
This node used to be on "Javadoc" Tab in Explorer. I don't care/mind if
it will be under Runtime TAB something like Javadoc TAB could be
opened from Options or JavaDoc Manager or.... but the result must be 
usable way to explore all Javadoc FSs "at once".


And as far as I undrestand your solution....it isn't what I want...
But for someone could be useful.

Rather there (in Javadoc Manager) could be a button invoking something
like "javadoc" TAB used to be...And if user wants s/he could
dock/undock into editor/explorer or whenewer s/he wishes.

But the first thing which has to be done is change J.Manager window
from MODAL mode to MODELESS 'cause as it is now...it doesn't alow any
efficient work and when mentioned features above will be implemented
the dialog won't allow to comfortable work with them...

The main problem with Vincent's suggestion is that the Javadoc Manager
is a modal dialog.  Particularly if one is using the internal browser,
doing it this way means the browser will pop up with the Javadoc, but
the browser will be disabled - not listening to mouse clicks.  That
would not be a pretty situation.

I don't see anything wrong with making the Javadoc Manager non-modal
(I can't think of any good reason why it needs to be a modal dialog),
but it is less clicks to access Javadoc via menu items, and I prefer
less clicks.  

No reason we can't do both, but I think the HIE folks might say that
the interface for accessing Javadoc and the interface for managing
Javadoc are not the same thing - I'd rather we don't ask for too many
changes, because the result might be that no changes at all get made
if we do.

So, I like the suggestion as a nice-to-have addition to the menu 
approach, but I'd prioritize the menu UI ahead of it.

Daniel, a question, do you really need access to the entire Javadoc FS
or just the index pages?  My habit has always been to bring up the
index page and navigate from there (just leaving the browser open). 
But maybe you have a different usage pattern than I do.

...hmmm...as I'm thinking now...
I don't realy need access to the entire Javadco FS :-)

But if I wish quick access to those index pages of more Javaadoc FSs..
I'm afraid that each time I need another index I had to go somewhere
in ide to reach it...and if I would have it in JavaDoc TAB...that's
easy to accceess whatever and whenever you want, am I right?

Yes and no :-)  It depends what you need to do.  With a Javadoc tab,
getting to a Javadoc index page means switch tabs, open root, possibly
open API folder, then double click or right click and choose Open. 
Seems like an awful lot of work - a menu is two clicks or a couple
keystrokes.  Isn't that faster and more convenient?

You're right:-) it is faster and convenient.
But how would you manage situation when you have mounted 10 JavaDoc
FSs? I'm personaly have mounted c.6 FSs now.

Have you tried Jesse's module (attached to this issue)?  I have a
submenu on my View menu 

Javadoc Indices ->
   NetBeans APIs
   JAXP1.1, DOM2, SAX2
   JavaMail APIs

It is quite nice.  Try it!

I've tried one of the first versions which creates a node under
RunTime TAB which satisfied my needs;-)

But as you described the functionalityu of another one, it sounds great!

The menu item will be in the next dev build. The documentation
filesystems node is not there (feel free to comment) since the
functionality is available through the Filesystems (and its children)
node in Tools | Options | IDE Configuration | System

Did you intentionally remove the mnemonic from the menu item? I found
it somewhat useful.

Verified. I'll file another issue for missing mnemonic.

This is not a bug, but if it's trivial, why not include it into 3.4.1?

Jesse, can your jar be seamlessly integrated into Netbeans 3.4.1? If
yes, what are the sources, I didn't see any qqqqq.java 1.4 -> 1.5
revision notes here.

Sincere, Maxym Mykhalchuk

As the discussion indicates, it is a defect, an usability one. IMO
trivial to fix thanks to Jesse's idea and code.

Extracted from CVS changelog:

Added files:
src/org/netbeans/modules/javadoc/search/IndexOverviewAction.java (1.2)

Modified files:
build.xml (1.28-1.29)
manifest.mf (1.51-1.52)
src/org/netbeans/modules/javadoc/search/JavadocSearchType.java (1.1-1.2)
src/org/netbeans/modules/javadoc/search/Bundle.properties (1.47-1.49)
src/org/netbeans/modules/javadoc/resources/mf-layer.xml (1.37-1.38)

Accepted for 3.4.1,
Thanks for the clarification, Svata

I suggest actually IndexOverviewAction.java 1.3 rather than 1.2, which
has an additional fix useful for doc sets with only one package in
them. Not very important though.

Hi. This issue is marked as 3.4.1_CANDIDATE. It means that it should be
integrated into release341 one branch. The plan at
http://www.netbeans.org/devhome/docs/releases/34/index.html expected beta1 to be
produced on Dec01. That did not happen due to a lot of outstanding not
integrated candidates like this one. 

Would it be possible to spend few minutes by backporting this fix? Thank you in
advance.

Merged from trunk into r-3.4.1:

/cvs/javadoc/build.xml,v  <--  build.xml
new revision: 1.27.30.1; previous revision: 1.27
/cvs/javadoc/manifest.mf,v  <--  manifest.mf
new revision: 1.50.18.1.2.1; previous revision: 1.50.18.1
/cvs/javadoc/src/org/netbeans/modules/javadoc/resources/mf-layer.xml,v
 <--  mf-layer.xml
new revision: 1.37.44.1; previous revision: 1.37
/cvs/javadoc/src/org/netbeans/modules/javadoc/search/Bundle.properties,v
 <--  Bundle.properties
new revision: 1.46.6.1.4.1; previous revision: 1.46.6.1
/cvs/javadoc/src/org/netbeans/modules/javadoc/search/IndexOverviewAction.java,v
 <--  IndexOverviewAction.java
new revision: 1.3.8.1; previous revision: 1.3
/cvs/javadoc/src/org/netbeans/modules/javadoc/search/JavadocSearchType.java,v
 <--  JavadocSearchType.java
new revision: 1.1.102.1; previous revision: 1.1

Sorry, forgot to remove the candidate keyword.

removing RELNOTE keyword; still keeping in readme in the 
What's Changed? section

Resolved for 3.3.x or earlier, no new info since then -> closing.