Bug 100138 - [doc] Confusing documentation in Project Configuration tutorial
Summary: [doc] Confusing documentation in Project Configuration tutorial
Status: VERIFIED FIXED
Alias: None
Product: JDT
Classification: Eclipse Project
Component: Core (show other bugs)
Version: 3.1   Edit
Hardware: PC Windows XP
: P3 normal (vote)
Target Milestone: 3.1 RC3   Edit
Assignee: Frederic Fusier CLA
QA Contact:
URL:
Whiteboard:
Keywords:
: 100140 (view as bug list)
Depends on:
Blocks:
 
Reported: 2005-06-15 04:48 EDT by David Saff CLA
Modified: 2005-06-16 17:23 EDT (History)
3 users (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 David Saff CLA 2005-06-15 04:48:10 EDT 
In RC2.  The Project Configuration tutorial contains a section "Nesting
resources in output directory".  The first two bullets read:

* The Java source files for a product are laid out in "sources" directory.
* Java class files are laid out in "deliverable" directory.  (Actually, this is
a typo, and should be "deliverables", but that's minor.)

This makes sense: one directory for source, another for class files.  However,
step 8 has the user create a source folder linked to "deliverables".  I can't
figure out why.
Comment 1 Frederic Fusier CLA 2005-06-15 05:23:12 EDT 
*** Bug 100140 has been marked as a duplicate of this bug. ***
Comment 2 Frederic Fusier CLA 2005-06-15 05:28:23 EDT 
Perhaps re-wording Layout on file system as:
. The Java source files for a product are laid out in <code>sources</code> and 
  <code>deliverables</code> directories.
. All Java class files are laid out in <code>deliverables</code> directory.
. Project needs to use some libraries located in 
  <code>deliverables/libraries</code> directory: 

would make it clearer?
Comment 3 David Saff CLA 2005-06-15 05:56:39 EDT 
That would make the section consistent, but taking a step back, would it make it
helpful?  What is the point of this section?  Is it helping the user with the
issues that arrive when "deliverables" is intended to have both class files and
jars, or both source and jars?  Having all three in one directory seems to add
confusion--it's not clear which steps are for resolving which issues.

My suggestion is that the first three bullet points stay exactly as they are,
and that the steps are updated with the assumption that there is no source in
"deliverables", which seems to me to be the most realistic user scenario.  If
that's undesireable, Frederic's new wording would at least make the section
consistent.
Comment 4 Frederic Fusier CLA 2005-06-15 06:20:12 EDT 
This scenario was based on a user true example (see bug 43859 comment 3 and
followings).
Philippe, do you agree to put this change in RC3?
Comment 5 Philipe Mulet CLA 2005-06-15 07:01:18 EDT 
+1 for RC3. Doc change doesn't need dual approval.

I would stick to Frederic's proposed change. The purpose of the tutorial is how
given some legacy code layout, one can configure some project classpath.
Comment 6 Frederic Fusier CLA 2005-06-15 08:10:27 EDT 
Fixed and released in HEAD
Comment 7 Olivier Thomann CLA 2005-06-16 17:23:48 EDT 
Verified using N20050616-0010 + JDT/Core HEAD