On Thu, 17 Jul 2003, Rankin, SE (Stephen) wrote:
> I was assuming that the export-full-docs target for starjava gave all the
> Starlink Java documentation, but the install target gives extra
> documentation in starjava/docs. Which should be included with the
> distribution, the export-full-docs or starjava/docs, or both?
Hi Steve,
the "export-full-docs" target in the main build file creates a full set of
"javadoc" documentation of all the packages that have a programming API.
This currently doesn't include the packages whose principle purpose is not
their API, but the various commands that they provide (although such
packages may and probably will make some of their API available).
User-level commands and UI help etc. are not documented using "javadoc",
so will never be exported by "export-full-docs".
So packages such as these are supposed (although I suspect SPLAT may be
the only one that does) provide additional documentation (SUN equivalents)
in their "src/docs" directory. All packages are supposed to carry LICENSE
files and miscelleaneous docs in "src/docs".
Now for the confusing part, which we've arrived at as the system just
developed. All packages also produce a local version of their APIs using
"javadoc" which actually ends up in "docs/<pkg_name>/javadocs", with the
stuff that was in "src/docs" being also copied to "docs/<pkg_name>". When
the package installs itself the whole of it's "docs" directory is copied
into place.
So what we have is some duplicated "javadoc" documentation between these
two methods.
What we really need is the "export-full-docs", plus any parts of
"starjava/docs" that are not javadocs (i.e. just throw all
"starjava/docs/<pkg_name>/javadocs" directories away).
Someone needs to redo the build files to enforce this somehow.
Any clearer (to anyone?).
Peter.
|