[dtp-dev] Documenting DTP API

[jograham@xxxxxxxxxx]

In previous threads and meetings we've been discussing a provisional API
statement for DTP 0.7. In the project lead/PMC meeting yesterday, we
decided to target the first draft of this statement for discussion in the
project lead/PMC meeting on Monday, 2/6, with the documentation being
circulated on Friday, 2/3, to allow time for review. This will then give
the DTP community a little over three weeks until 2/24, which is the
Callisto API freeze, to revise and finalize the statement.

In the project lead/PMC meeting, I took an action item to suggest a
documentation format, based on JavaDoc and PDE extension point
documentation, that the team could use to insure consistency and ease of
review. So, here's my suggestion:

Let's create an help plug-in for this purpose. Following the platform
example, we could call it "org.eclipse.datatools.doc.isv," and it would
(ultimately) house all DTP extender documentation for the full DTP feature.
(Other documentation plug-ins would be created for the other DTP
subfeatures.) As an experiment I created a help plug-in, to which I added
some sample extension point and API documentation to the "Reference"
section. (See attached images.)  If we agree to use this plug-in as the
review vehicle, here's what would be required:

(1) DTP committers making API statements would update the extension point
documentation and Javadoc in DTP CVS.
(2) A list of extension points (plug-in name/extension point name) and API
packages would be sent to me. Since the JavaDoc will be generated for all
"public" members in specified packages, any members that are not for API
consideration should be clearly marked as "NON-API" for each class
involved.

To meet the deadlines mentioned above, (1) and (2) would need to be
completed by the end of Thursday, 2/2.  Next, on Friday morning (2/3), I
will extract the extension point documentation and build the JavaDoc. It
will then import these into the help plug-in, zip it, and place it on the
download site by the end of the day. Anyone wishing to review the API
declaration could then download and install the plug-in in Eclipse, and use
the Eclipse Help system to read the materials.

Thoughts?

Regards,
John Graham
Eclipse Data Tools Platform PMC
Staff Software Engineer
Sybase, Inc.

(See attached file: dtp_doc_plugin1.JPG)(See attached file:
dtp_doc_plugin2.JPG)

Attachment: dtp_doc_plugin1.JPG
Description: JPEG image

Attachment: dtp_doc_plugin2.JPG
Description: JPEG image