Context-sensitive help for the Lotus Notes API for Java

Ferdinand Prantl

Saturday, 29 July 2006

Domino Javadoc Generator

Why is the Domino Designer Help not enough?

The Domino Designer Help serves good while developing in the Domino Designer. They are tightly integrated speaking about the auto-complete feature of editors for the formula language and LotusScript.

However, there is usually other IDE used for the development of external applications integrating Domino via the Notes API for Java. Such IDEs integrate the most common format of the source code documentation for Java - packed sources and packed javadoc documentation. These sources are used to display a context-sensitive help for the classes and methods from the corresponding Java package.

While IBM does not provide a package with the javadoc documentation for the Notes API for Java every searching for an information about a class or method means opening the Domino Designer Help and looking for an answer there.

There is more lost then only the convenience; there are other productivity features which are standard today and which are not available with the Domino Designer Help. See further.

What does it bring having sources and javadoc of an API?

Being able to stay in the IDE for Java and not to have to switch to a separate documentation browser saves time of developers and helps to keep them concentrated. There are also other improvements which a resonable IDE for offers:

  • Auto-complete for names of classes and methods typed in the source code editor. It makes typing faster. Just seeing the methods available can save a jump to help looking for the right one.

  • Object-browser for classes and interfaces presenting the API in a hierarchic tree-like form. It helps for the orientation in the API while picking class a suitable for the current task.

  • Help-popups are context-sensitive windows with a javadoc content displayed for classes and methods when the mouse cursor is hovering over their names. It is not always necessary to sieve through the documentation just to know what the method does.

  • Links to the documentation can be followed just by selecting names of a classes or methods and asking for a help for them (usually by pressing the key F1). There is no need first to search in the external documentation for the class or method. You can be pointed to the right one automatically.

  • A developer can jump to the source code to have method prototypes together with their javacod comments in the editor instead of switching to a help pane.

These features increase remarkably productivity of developers. See further how they look like.


In this example a developer wants to call a method named "recycle". Let us see how the editor helps without an attached source code or a javadoc documentation:

And let us see how it improves after providing the editor with the necessary data:

The first paragraph of the documentation is usually enough to pick the right method without reading the full documentation.


In this example a developer wants to see briefly what the method does by hovering the mouse over its name without opening the documentation. Let us see what happens without an attached source code or a javadoc documentation:

And let us see how it improves after providing the editor with the necessary data:

The window with the documentation can be enlarged and it can be also pinned not to hide when the mouse has moved or a button has been clicked.

Links to the documentation

In this example a developer wants to read more about the method. Just by pressing a single key (F1) he gets a help pane with an offer what documentation is available for the context of the current cursor position:

And after clicking on the most fitting possibility (the link to a javadoc with the prototype of the method) we get right to the documentation:

There is no need to switch applications, type the name of the method again and scroll to the beginning of the documentation.

Jump to the source code

In this example a developer wants to get to the source code of the method to see what it does. Just by pressing a single key (F3) while letting the cursor on the name of the method he gets to a file with the definition of it. Folding of comments and bodies of methods is optional:

Well, sources of the Notes API are not public, thus it does not help much to learn about its internals. At least it is possible to read sources for the javadoc documentation and see the layout of the class. And probably copy & paste it somewhere; after all, it is a full editor for Java sources...

Configuration of an IDE

There are two files ready to be integrated with an IDE for Java:

Pseudo-source code - a zipped archive with source files defining the interfaces. Sources of classes are provided with empty bodies just to serve the generation of the javadoc documentation. They cannot be used to produce the real Notes API :-)

Javadoc documentation - a zipped archive with the generated HTML documentation by the standard javadoc toll from JDK.

This is an example how to configure these files in a build path of an Eclipse project referencing the Notes API already:

The fields "Source attachment" and "Javadoc location" were changed to point to the files mentioned above.

Configuration dialogs of other IDEs for Java (NetBeans, IntelliJ) contains similar settings.

Enjoy improved convenience and productivity! :-) LogoSupport This Project
Copyright © 2006 Ferdinand Prantl