docs for classpath and prefs (#168)

docs/using_the_feature_classpath.md

@@ -1,14 +1,80 @@
 ## Understanding the Classpath with the Bazel Eclipse Feature
 
-Under construction.
+BEF ultimately computes classpath information and maps it into the existing Java Developer Tools (JDT) plugins of Eclipse.
+This works well, but there are some caveats to this mapping.
+The caveats come from the fact that JDT grew up around the Maven build system, and Bazel is a more flexible build.
 
-Topics:
+### Requires conforming Java packages
 
-- Global search classpath
-- Bazel Classpath container - how to see it, what to look for
-- Configure the JDK manually for now, later should be read from .bazelrc
-- Inside the .classpath file
-- Inside the .project file
+The top-level README links into a major set of limitations we have with mapping Bazel packages into JDT.
+The limitations allow us to use JDT without modifications.
+
+- [Conforming Java Packages](conforming_java_packages.md)
+
+### Classpaths are scoped to each Eclipse project
+
+Each Eclipse project maps to a single Bazel package.
+For example, Bazel package *//projects/libs/apple-api* maps to an Eclipse project named *apple-api*.
+There is a *Bazel Classpath Container* node inside of the *apple-api* project, that is the computed
+  classpath from the Bazel BUILD file for the package.
+
+### There are two classpaths per project
+
+The *Bazel Classpath Container* actually configures two classpaths with JDT:
+- the main classpath
+- the test classpath
+
+The way this is computed is as follows:
+
+- any dependency within the package that only appears in *java_test* target(s) is added to the test classpath
+- all other dependencies for any java rule in the package get added to the main classpath
+
+### Configuring the JDK
+
+Within Bazel, every Java rule could target a different JDK version.
+However, BEF currently only supports a single global JDK setting for configuration during import.
+It is configured by the source level set on the command line
+  (or [.bazelrc file](https://docs.bazel.build/versions/master/guide.html#bazelrc-the-bazel-configuration-file))
+  [javacopt](https://docs.bazel.build/versions/master/user-manual.html#flag--javacopt) option:
+
+```
+--javacopt "-source 8 -target 8"
+```
+
+While this is a limitation, this is only the default set during import.
+You may then manually configure the JDK by configuring the Build Path of any Eclipse Project.
+
+- Right click on the project in the *Package Explorer*
+- Click *Build Path -> Configure Build Path...*
+- Click the *Libraries* tab
+- Click on the existing JRE or JDK entry, and then click *Remove*
+- Click *Add Library... -> JRE System Library* and then make your choice
+
+### Global Search Classpath
+
+Currently, this is an experimental feature.
+See [Global Search Classpath](https://github.com/salesforce/bazel-eclipse/issues/161) issue for status.
+
+This feature provides a benefit when working with large Bazel workspaces.
+With a large workspace, during import you will likely only choose to import a handful of packages.
+BEF will configure an Eclipse project for each of those packages, with the proper classpath.
+
+However, the Eclipse *Open Type* dialog will then only have visibility into the types found in the classpaths of the
+  imported projects.
+Types that are available in the Bazel workspace, but not in those projects, will not be visible to *Open Type*.
+This makes it hard to discover useful types when doing development.
+
+The *Global Search Classpath* is a feature to resolve this issue.
+It scans the external jar directory of the Bazel build, and adds all found jars to a synthetic classpath node
+  nested under the Bazel Workspace project in the Package Explorer.
+By having them appear in a classpath object, JDT can now find all enclosed types.
+
+To enable this feature do the following *before* importing packages into your workspace:  
+- *Eclipse -> Preferences -> Bazel* (exact menu varies by platform)
+- Click the *Enable global classpath search* option.
+
+Note that the feature may not work for all use cases.
+Check the Issue linked above for details.
 
 ### Next Topic: Launching binaries and tests from Eclipse
 

docs/using_the_feature_import.md

@@ -25,7 +25,7 @@ For example, if this is in your *.bazelrc* file, JDK 8 will be in every project'
 build --javacopt=-source 8 -target 10
 ```
 
-After import, you are free to change the JDK for each project using the Eclipse Build Path user interface.
+After import, you are free to [change the JDK](using_the_feature_classpath.md) for each project using the Eclipse Build Path user interface.
 Please see [Support package level JDK configuration for Build Path](https://github.com/salesforce/bazel-eclipse/issues/89) for status on improvement.
 
 #### Limitation: Only Import Conforming Java Packages

docs/using_the_feature_launching.md

@@ -51,3 +51,7 @@ Method 2: Package Explorer context menu
 
 :warning: the standard JUnit Launcher *JUnit Test* does not work.
 [Issue 18](https://github.com/salesforce/bazel-eclipse/issues/18) tracks that work item.
+
+### Next Topic: Setting Preferences
+
+The next page in our guide discusses the [Preferences](using_the_feature_preferences.md) available with the Bazel Eclipse Feature.

docs/using_the_feature_preferences.md

@@ -0,0 +1,26 @@
+## Using the Bazel Eclipse Feature: Preferences
+
+Once you have your initial Eclipse workspace up and running, you may want to set some preferences.
+
+### Workspace Preferences
+
+BEF supports a pane in the Eclipse preferences editor.
+The way to open the preferences editor varies by platform.
+On Mac, open it by navigating to *Eclipse -> Preferences -> Bazel*.
+
+What each preference controls is documented in topic specific locations of our documentation.
+
+### Global Preferences
+
+If you are a power user of BEF, and create many workspaces, you may wish to save common defaults to a global file.
+This will save time when creating a new BEF workspace.
+
+File location: **~/.bazel/eclipse.properties**
+
+```
+# always default Bazel executable to be bazelisk in my non-standard location
+BAZEL_PATH=/Users/mbenioff/dev/tools/bazelisk-darwin-amd64
+```
+
+Instead of documenting the available properties here (which would get outdated),
+  please search for the *BazelPreferenceKeys.java* class in the code base.

plugin-core/src/main/java/com/salesforce/bazel/eclipse/preferences/BazelPreferenceInitializer.java

@@ -53,20 +53,20 @@ public class BazelPreferenceInitializer extends AbstractPreferenceInitializer {
     @Override
     public void initializeDefaultPreferences() {
         IPreferenceStore store = BazelPluginActivator.getInstance().getPreferenceStore();
-        Properties defaultPrefs = loadMasterPreferences();
+        Properties globalPrefs = loadGlobalPreferences();
 
         // USER FACING PREFS (visible on Prefs page)
 
         String bazelExecLocationFromEnv = BazelExecutableUtil.which("bazel", "/usr/local/bin/bazel");
-        String value = defaultPrefs.getProperty(BazelPreferenceKeys.BAZEL_PATH_PREF_NAME, bazelExecLocationFromEnv);
+        String value = globalPrefs.getProperty(BazelPreferenceKeys.BAZEL_PATH_PREF_NAME, bazelExecLocationFromEnv);
         store.setDefault(BazelPreferenceKeys.BAZEL_PATH_PREF_NAME, value);
 
         // enable global classpath search by default
-        value = defaultPrefs.getProperty(BazelPreferenceKeys.GLOBALCLASSPATH_SEARCH_PREF_NAME, "false");
+        value = globalPrefs.getProperty(BazelPreferenceKeys.GLOBALCLASSPATH_SEARCH_PREF_NAME, "false");
         store.setDefault(BazelPreferenceKeys.GLOBALCLASSPATH_SEARCH_PREF_NAME, "true".equals(value));
 
         // BEF DEVELOPER PREFS (for efficient repetitive testing of BEF)
-        value = defaultPrefs.getProperty(BazelPreferenceKeys.BAZEL_DEFAULT_WORKSPACE_PATH_PREF_NAME);
+        value = globalPrefs.getProperty(BazelPreferenceKeys.BAZEL_DEFAULT_WORKSPACE_PATH_PREF_NAME);
         if (value != null) {
             store.setDefault(BazelPreferenceKeys.BAZEL_DEFAULT_WORKSPACE_PATH_PREF_NAME, value);
         }
@@ -77,7 +77,7 @@ public void initializeDefaultPreferences() {
      * preferences to be used for any new Eclipse workspace. This is a savior for those of us who 
      * work on BEF and create new Elipse workspaces all the time. Might be useful for regular users too.
      */
-    private Properties loadMasterPreferences() {
+    private Properties loadGlobalPreferences() {
         Properties masterProperties = new Properties();
         String userHome = System.getProperty("user.home");
         File masterPropertiesFile = new File(userHome+File.separator+".bazel", "eclipse.properties");