Generates Javadoc documentation for Java classes of the Lotus Notes API together with pseudo-source code. This standard Javadoc documentation can be integrated with IDEs like Eclipse. The generator depends on an installation of Lotus Notes and Domino Designer.
|
|
Tutorial Slides |
Project News
|
This project aims to create a documentation to the Lotus Notes API for Java in a standard format common in the Java comunity and accepted by the most IDEs for Java.
The Lotus Notes API is delivered as a Java archive together with the original documentation in the native format of a Domino database with the IBM Domino Designer. The documentation can be read only in the Lotus Notes. Java-oriented tools cannot use it to display a description of a Java class, to browse classes and their methods or to offer an automatic code insertion based on a Java object and its class.
The goal is to create a Javadoc documentation together with a pseudo-source code of the Lotus Notes API. The documentation can be viewed, indexed and integrated to IDEs. The pseudo-source code can be integrated to IDEs to support object browsing and automatic source code insertion.
See http://domino-javadoc.sourceforge.net for the most recent version and more information.
This is achieved by generating sources to public Lotus Notes interfaces and classes without bodies of methods. The interfaces and classes are extracted from the Java archive with the Lotus Notes API using reflection. They exist only for documentation purposes; they do not contain any executable code. Content of Javadoc comments injected to the sources is converted from the help to the Domino Designer where it resides in the Domino rich text format using the Lotus Notes API. The Javadoc documentation is produced by calling the standard tools from a JDK.
There are more steps on the way from the original JAR (Java archive with the code) and NSF (Notes database with the documentation). XML/XSLT is used to bridge their output. The process of the generation can be summarized in the following steps:
Prerequisities:
java -classpath "jar/jarek.jar;<JAVA_HOME>/jre/lib/rt.jar; <JAVA_HOME>/lib/tools.jar;<NOTES_HOME>/jvm/lib/ext/Notes.jar; <NOTES_HOME>/jvm/lib/xml.jar" sk.host.prantl.jarek.Extractor -aj <NOTES_HOME>/jvm/lib/ext/Notes.jar -p lotus.domino -r lotus.domino._UserObjectBaseStub -r lotus.domino._NotesErrorStub -a lotus.domino.NotesError >types.xml
xsltproc --stringparam output-directory ./generated --stringparam documentation-file topics.xml generate-java.xsl types.xml
xsltproc --stringparam output-directory ./generated/lotus/domino generate-html.xsl documentation.xml
javadoc -classpath "jar/jarek.jar;<JAVA_HOME>/jre/lib/rt.jar; <JAVA_HOME>/lib/tools.jar;<NOTES_HOME>/jvm/lib/ext/Notes.jar; <NOTES_HOME>/jvm/lib/xml.jar" -d ./javadoc -encoding iso8859-1 -sourcepath ./generated lotus.domino
See the Ant build script generate.xml performing the steps above together with packing the output for a convenient distribution and integration to IDEs like Eclipse. See the batch file setenv.cmd setting up environment variables required for the tools.
It is sensible to create a common master directory for the others packages, either dependencies of this package or other new ones. It helps keeping all the unpacked packages in good order, for example:
d:\packages d:\packages\package1 d:\packages\package2 ...
Names of the packages rarely clash with the others. It is usual to use the name of the package for the name of the directory, for example:
d:\packages\domino-javadoc
cd d:\packages\domino-javadoc unzip domino-javadoc-0.4-bin.zip
setenv.cmd
ant -f generate.xml
The generated files are provided in a downloadable archive domino-javadoc-0.4-out.zip for convenience.
There are several files in the master directory introducing briefly the package, its version, history, authors and license. The subdirectories are:
Sources:
Binaries:
Output:
Home with the latest version:
Slides with an introduction and a tutorial:
Bug reports, questions and suggestions are kindly expected at prantl@sourceforge.net.
It is sensible to create a common master directory for the others packages, either dependencies of this package or other new ones. It helps keeping all the unpacked packages in good order, for example:
d:\packages d:\packages\package1-version1 d:\packages\package2-version2 ...
Names of the packages rarely clash with the others. It is usual to use the name of the package with the version stamp for the name of the directory (name without version is used for the compiled installation package), for example:
d:\packages\domino-javadoc-0.4
cd d:\packages\domino-javadoc-0.4 unzip domino-javadoc-0.4-src.zip
Correct the path to your local Java SDK installation, Lotus Notes directory and the paths to other tools in the example batch file and build the tool:
setenv.cmd ant
2006/08/09 version 0.4
! wrong command-line parameter handling for DTD (-d|--document => -t|--dxl-dtd) ! missing path to a DXL DTD in Ant script generate.xml ~ examples generated in external files by default (configurable) + templates for the output conversion of tables + links to classes, methods, examples and other pages recognized and generated + additional documentation pages processed + the first page of the Java documentation copied as the overview page + support for the sections "see also" added
2006/07/29 version 0.3
+ XSL templates extracting and cleaning the documentation from DXL + XSL template creating an empty Java source of classes from the Notes API with the documentation from the generated XML files
2006/07/28 version 0.2
+ extractor of the documentation to Java classes from the Notes API
2006/07/23 version 0.1
+ Java class analyzer and description generator adapted from the project jarin (http://jarin.sourceforge.net) + Ant script to build and run this tool
+ introduce new documentation elements - parameters and the result of a method to be able to write them as javadoc tags ~ support nested classes as nested, not converted to global ones ~ optimize XSL tempates (nested replacing and nested searching in the generation) + generate a real Eclipse help + compile a CHM file from the pseudo-javadoc