[Cs-studio-core] Javadoc for 'core' plugins?

[Kasemir, K. <kas...@or...>]

Hi:

At the SLAC EPICS meeting one goal for 3.2 was to have Javadoc for the
core plugins.

One can 'export' Javadoc for a plugin from within the IDE, but it's a
manual and tedious process.
You need to select all 'core' plugins one by one, ... and you get one big
Javadoc set without any correlation to the plugins. Just a list of
packages and classes.

I didn't find a headless invocation for this.

So I created a little python script that locates all 'core' plugins and
their packages, it's under build/make_javadoc.py.
The idea was to create an ant file for running javadoc with 'group'
statements that group the Java packages by plugin.
The "Overview" javadoc page would then list all plugins and their
packages, and you can drill down from there.

This doesn't work for 2 reasons:
Many source files contain annotations, and javadoc crashes on unknown
annotations,
 http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6442982
 Would have to add junit, ... anything that defines annotations to the
javadoc classpath, which is practically impossible without somehow hooking
into the headless build which knows what the classpath should be.

 
Even when limiting it to plugins that don't use unknown annotations, the
"grouping" doesn't work because packages of the same name may be in
multiple plugins, which results in another javadoc error.



So I don't see an easy way to do this outside of the headless build, and
the headless build doesn't provide javadoc, either.


What would be possible is an approach similar to the 'common' product:
For each core plugin that we want to document, we manually add the plugin
src path,
the <group..> command that lists the packages of the plugin,
and the jar files that define annotations to an ant javadoc.xml.
Not sure if it's worth it.

-Kay