This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 49309

Summary: Show default help page when request made to display invalid ID
Product: platform Reporter: Chris Kutler <ckutler>
Component: Help SystemAssignee: Jaroslav Havlin <jhavlin>
Status: NEW ---    
Severity: blocker CC: jglick, johnjullion
Priority: P3    
Version: 4.x   
Hardware: All   
OS: All   
Issue Type: ENHANCEMENT Exception Reporter:

Description Chris Kutler 2004-09-20 19:58:59 UTC
About
http://www.netbeans.org/download/dev/javadoc/JavaHelpAPI/org/netbeans/api/javahelp/doc-files/help-guide.html

Instead of instructing programmers do do this:

    public HelpCtx getHelp() {
        return new
HelpCtx("org.netbeans.modules.xml.core.wizard.DocumentPanel");
 
    }

We might instead want to tell them to do something
like the following. That way, the user sees the
system respond, the user does not see NPEs, and we
get error messages that help us solve the problem.

String id =
"org.netbeans.modules.xml.core.wizard.DocumentPanel";
Help help =
(Help)Lookup.getDefault().lookup(Help.class);
if (help != null && help.isValidID(id,
true).booleanValue()) {
    help.showHelp(new HelpCtx(id));
} else {
    <send to error out>"Invalid Help ID " + id +
"in class " + <class name>;
    help.showHelp(new HelpCtx(<the default id>));
}

By the way, it would be nice if we implemented
some check like this in existing code.
Comment 1 Jesse Glick 2004-09-20 20:57:27 UTC
I'm afraid I don't know what you're talking about. What NPEs?
Comment 2 Chris Kutler 2004-09-21 00:19:18 UTC
To recreate:

In the build, go to ide4/modules/docs

Unjar monitor.jar

Edit
ide4\modules\docs\monitor\org\netbeans\modules\web\monitor\docs\monitorMap.jhm

Change these 2 lines by putting X in the target (thus breaking the map
id).

	<mapID target="ctx_monitorintroX" url="monitor/ctx_monitorintro.html" />

	<mapID target="org.netbeans.modules.web.monitor.client.MonitorActionX"
url="monitor/ctx_monitorintro.html" />

Rejar and start the IDE.

Open the help viewer on some topic.

Click Window > HTTP Monitor.

Click in the HTTP Monitor and Press F1. The viewer appears but the
topic does not change.

Look in the messages.log file. The message is as follows (which is an
improvement from earlier versions)

[org.netbeans.modules.javahelp] Warning: the JavaHelp topic ID
ctx_monitorintro was not found.


-------

So, to be more clear. What I am asking for is:

1. Edit this file:
http://www.netbeans.org/download/dev/javadoc/JavaHelpAPI/org/netbeans/api/javahelp/doc-files/help-guide.html

a. Where it gives examples of how to call showhelp, enhance the
examples to show how to verify the id is valid before calling showhelp.

b. If the id is invalid, call showhelp on the default topic instead,
so that the user sees something sensible (the default topic says that
there is not an available topic).

c. When the id is not valid, send a message to the log as to what
class (and maybe even what UI) is using the bad id so that we can
figure out which writer and which engineer need to make the fix.

2. Perhaps mention to the NB engineers that they do this validation in
  new code at the least, and in existing code when and if they happen
to be mucking about.
Comment 3 Jesse Glick 2004-09-21 15:26:18 UTC
The API docs are fine as they stand. Most code simply declares a help
ID. The handful of pieces of code that show help in response to
something - the dialog infrastructure, and a few unusual dialogs (not
most) - are also fine, they just ask the help system to display a
given ID. The help system is responsible for what happens after that.
If you want the help system to do something different with an invalid
ID than what it does now, file an RFE (core/javahelp).

So #1a, #1b, and #2 are invalid. #1c is simply impractical; use grep.
Comment 4 Chris Kutler 2004-09-21 17:35:04 UTC
Correction - clone error. Need to replace help.showHelp with return

String id =
"org.netbeans.modules.xml.core.wizard.DocumentPanel";
Help help =
(Help)Lookup.getDefault().lookup(Help.class);
if (help != null && help.isValidID(id,
true).booleanValue()) {
    return new HelpCtx(id));
} else {
    <send to error out>"Invalid Help ID " + id +
"in class " + <class name>;
    return new HelpCtx(HelpCtx.DEFAULT_HELP);
}

In my clumsy way I am asking programmers to verifiy the help id and,
if invalid, display the default help. 
Comment 5 Jesse Glick 2004-09-21 20:53:37 UTC
Too much code, too clumsy. We do not want that long block of code
copied everywhere HelpCtx is produced. Better to extract the ID ->
source mapping mechanically.
Comment 6 Chris Kutler 2004-09-21 22:18:38 UTC
OK, there are 2 issues here. The more important one is that the user
sees good IDE behavior. That is, if the user presses F1 or Help, the
user either gets the correct topic or the default topic. Here is a
solution to that. Modify the code examples to show the programmers how
to validate the ID before blindly using it.

String id =
"org.netbeans.modules.xml.core.wizard.DocumentPanel";
Help help =
(Help)Lookup.getDefault().lookup(Help.class);
if (help != null && help.isValidID(id,
true).booleanValue()) {
    return new HelpCtx(id));
} else {
    return new HelpCtx(HelpCtx.DEFAULT_HELP);
}

The second issue was to beg for some better error feedback. I give up
in that, but I wish you would consider #1. As I showed in my steps to
reproduce, the UI response is bad from the users' point of view.
Comment 7 Jesse Glick 2004-09-21 22:51:25 UTC
Reassigning to javahelp integration module for second #1, i.e. if a
request arrives to display an invalid ID, when opening the help
viewer, should switch to the "fallback" page in the master help set
rather than leaving the page untouched. (Or don't show help viewer at
all.)

Have no plans to modify any code examples. The simple code

  return new HelpCtx("foo");

is correct and suffices.

Re. second #2, i.e. better error reporting, sorry but as I have
explained several times I don't think there is anything better that
can be done without massively cluttering the source base.
Comment 8 Antonin Nebuzelsky 2008-11-14 15:19:33 UTC
Reassigning to the new "core/help system" owner obarbashov.
Comment 9 Alexei Mokeev 2009-03-05 13:57:50 UTC
Moving JH issues to Victor.