Re: [tycho-user] javadoc - best practices

["Jens v.P." <eclipse-mailinglist@xxxxxxxxx>]

On 18.12.11 21:12, Igor Fedorenko wrote:
> I am mostly looking for the specification of the documentation plugin
> layout, what extension points it needs to provide, if any, how and where
> javadoc needs to be packages, same for examples, documentation and
> everything else. I basically need to understand the requirements before
> I can suggest anything.

A typical "documentation plugin" (or help plugin) contains

- a manifest, with a dependency to eclipse help, e.g.,

    Manifest-Version: 1.0
    Require-Bundle: org.eclipse.help;bundle-version="3.2.0"
    Bundle-SymbolicName: my.project.doc;singleton:=true

- at least one primary toc.xml, describing the table of contents. E.g.,

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="My Documentation">
<topic href="html/overview.html" label="Overview">
</topic>
<topic href="reference/api/index.html" label="API Reference">
</topic>

<topic href="html/plugins.html" label="Other Documentation">
<topic href="html/help1.html" label="Other help file"></topic>
<topic href="html/help2.html" label="Another help file"></topic>
</topic>
</toc>

Other "tocs" may exist, providing context help etc.

- javadoc. While there are several options for storing the javadoc, 
either in a zip or a folder. Since usually the plugin itself is a jar, 
the javadoc is often contained in a folder reference/api. Ssome projects 
(such as GEF) provide the javadoc in separated plugins, similar to 
source plugins, and then reference to these plugins. However, it's 
easier to create a single javadoc for all plugins, as it makes linking 
much simplier -- although it might be easier to automatically generate 
these plugins similar to source plugins.

- a plugin.xml, registering the toc, and also the javadoc. Javadoc is to 
be registered for each plugin for which the doc plugin provides the 
javadoc. E.g.,

<plugin>
<extension point="org.eclipse.help.toc">
<toc  file="toc.xml" primary="true" />
</extension>

<extension point="org.eclipse.pde.core.javadoc">
<javadoc path="reference/api">
<plugin id="my.plugin1"/>
        ...
<plugin id="my.pluginn"/>
</javadoc>
</extension>

- html help files, these files are referenced from the toc.xml (and 
other toc files). Some projects use plain html files. Others use 
wiki-like files which are then transformed into html files (e.g., mylyn 
wiki as demonstrated in Chris' minerva project, AFAIK xtext provides 
it's own documentation DSL and generators), in which case the 
transformation has to be invoked somehow

Cheers,
Jens