= domino-javadoc 0.4 =

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.

<toc>
<sourceforge domino-javadoc 173113 slides>

----

== overview ==

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.

----

== details ==

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:

1) Extract definitions of interfaces and classes from the Notes API for Java
   (Notes.jar) to an XML file.
2) Convert the documentation for the Java interfaces and classes from
   a Notes database with the help to the Notes API (help7_designer.nsf)
   exported as DXL to an XML file.
3) Create pseudo-source code using the XML file with definitions of Java
   objects and an XML file with their documentation.
4) Generate a Javadoc documentation using the tool javadoc from JDK.

Prerequisities:

* Lotus Notes and Domino Designer (the tested version is 7.0.1)
* JDK (the tested version is 1.5.0)
* Apache Ant (the tested version is 1.6.5)
* EXSLT processor (the tested version is xsltproc gnu-xml with libxml-20615,
  libxslt-10112 and libexslt-810)

1) Extract class and interface definitions

 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

2) Convert the documentation for the interfaces and classes:

 java -classpath "jar/domino-javadoc.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.domino_javadoc.Extractor >documentation.xml

3) Create pseudo-source code:

 xsltproc --stringparam output-directory ./generated
  --stringparam documentation-file documentation.xml
  generate-java.xsl types.xml

4) Generate additional documentation pages:

 xsltproc --stringparam output-directory ./generated/lotus/domino
  generate-html.xsl documentation.xml

5) Generate a Javadoc documentation:

 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.

----

== installation ==

* create a directory for the package

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

* unpack the chosen ''bin'' package into this directory

 cd d:\packages\domino-javadoc
 unzip domino-javadoc-0.4-bin.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 run it

 setenv.cmd

* produce the documentation

 ant -f generate.xml

The generated files are provided in a downloadable archive
domino-javadoc-0.4-out.zip for convenience.

----

== package structure ==

There are several files in the master directory introducing briefly the package, its version, history, authors and license. The subdirectories are:

* slides - sources of the general documentation
* java   - sources of Java tools
* *.xsl  - XSL templates

----

== list of deliverables ==

Sources:

* domino-javadoc-0.4-src.zip - original sources

Binaries:

* domino-javadoc-0.4-bin.zip - binaries and a source code documentation

Output:

* domino-javadoc-0.4-out.zip - a generated Lotus Notes API documentation

----

== related links ==

Home with the latest version:

* http://domino-javadoc.sourceforge.net/

Slides with an introduction and a tutorial:

* http://domino-javadoc.sourceforge.net/slides

Bug reports, questions and suggestions are kindly expected
at prantl@users.sourceforge.net.

----

== build from sources ==

* create a directory for the package sources

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

* unpack the chosen source package package into this directory (if there is a common master directory inside the source package, unpack its content into the new directory)

 cd d:\packages\domino-javadoc-0.4
 unzip domino-javadoc-0.4-src.zip

* build the binary package

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

----

== history of changes ==

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

== planned improvements ==

+ 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