Bug 274522 - javadoc not included in build
Summary: javadoc not included in build
Status: RESOLVED FIXED
Alias: None
Product: Equinox
Classification: Eclipse Project
Component: p2 (show other bugs)
Version: 3.5   Edit
Hardware: PC Mac OS X - Carbon (unsup.)
: P3 major (vote)
Target Milestone: 3.6   Edit
Assignee: P2 Inbox CLA
QA Contact:
URL:
Whiteboard:
Keywords: Documentation
Depends on:
Blocks:
 
Reported: 2009-04-30 10:25 EDT by Jeff McAffer CLA
Modified: 2010-06-02 15:55 EDT (History)
1 user (show)

See Also:

Attachments
Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Jeff McAffer CLA 2009-04-30 10:25:02 EDT 
as of i0421 the javadoc for p2 is not included in the builds.  The p2 API is provisional but should be included in the release so that people can get started on using p2.
Comment 1 John Arthorne CLA 2009-04-30 13:42:45 EDT 
I'm not sure about this. Some of our provisional API is real candidate API with complete javadoc specs, but quite a lot of it is bare classes with few or no class/method comments (at best it roughly delineates internal code from what could some day be turned into API). Since there has been no effort on cleaning it up, it's quite possible some of the comments that do exist could be wrong or misleading. I'd be embarrassed to generate javadoc for some of this stuff and include it alongside real API in our reference docs... We're also not using @provisional or any other such comment to distinguish real from provisional API at the doc level, which could be misleading.
Comment 2 Jeff McAffer CLA 2009-05-01 08:09:22 EDT 
understood.  this is double-edged sword.  We want people to use this stuff and help evolve the function and API.  They can't do that unless there is some doc to help them understand what's going on.  Likely we can take an incremental approach where all provisiaional API types have a type comment with real content and a "provisional warning"  (see http://wiki.eclipse.org/Provisional_API_Guidelines_Update_Proposal).  Then iteratively add more and more comments to the high traffic/interesting types.

Publishing the Javadoc or not is a somewhat separate issue.  Not publishing it certainly hides the shortcomings from some people. OTOH, those people seem to like using Javadoc so we are discouraging them from adopting p2.
Comment 3 Thomas Watson CLA 2010-06-02 15:54:34 EDT 
I think this can be closed as fixed.  There are a few packages still are not javadoc'ed in p2. But that is covered in another bug marked for 3.6.1.
Comment 4 Thomas Watson CLA 2010-06-02 15:55:18 EDT 
See bug 314296 for ongoing tracking of the missing javadoc.