Document usage of BFG and modify usage to be more ergonomic

README.md

@@ -1,21 +1,64 @@
 [![Build Status](https://ci.bazel.io/buildStatus/icon?job=BUILD_file_generator)](https://ci.bazel.io/job/BUILD_file_generator)
 
-# BUILD File Generator
+# BUILD File Generator (BFG)
 
-BUILD File Generator generates Bazel BUILD files for Java code.
+BUILD File Generator, or BFG for short, is a tool for generating Bazel BUILD files from one's source code. Instead of manually going through your project and creating BUILD files and their appropriate build rules, you can rely on BFG to do it for you! 
 
-1. It reads all `.java` files, and extracts the class dependency graph.
-2. Computes the strongly connected components of the graph.
-3. For each component, creates a `java_library` rule.
+An example project can be found here. TODO
+
+### Why is it useful?
+
+Bazel promises fast and correct builds, _especially_ for incremental builds. Rather than rebuild your entire codebase, Bazel _only_ rebuilds what is necessary, the targets that you have changed. For the remainder of your code, it relies on cached versions. 
+
+There is one caveat to this fast incremental performance, though. It is dependent on the granularity of your targets. At one extreme, the least granular end, you can define a single glob for your entire project. This would be the quickest way to get your project using Bazel. However, it comes at the cost of eradicating any of Bazel's incremental build performance. On the other end, you can try to manually define the most granular targets possible, a single rule per file, collapsing any cyclic dependencies into the same target. This would ensure you make use of Bazel's blazingly fast incremental builds. However, it is extremely tedious, and somewhat annoying to maintain.
+
+BFG automates this difficult tango.
 
 ## Usage
 
-TODO
+BFG is composed of two general components
+
+1. Language specific parsers (LSP)
+2. The BFG binary
+
+The LSPs read your source code and generate a class dependency graph in the form of a protobuf. To generate your BUILD files, you pass the generated protobuf into the BFG binary.
+
+### Step 0: Installation Instructions
+
+To install BFG...TODO
+
+### Step 1: Using LSPs to generate dependency graphs
+
+TODO(bazel-devel): add explanation and valid example arguments.
+
+```bash
+bazel run //lang:JavaSourceFileParserCli <TODO>
+```
+
+This generates a protobuf at TODO.
+TODO(bazel-devel): add clear protocol for how the protos are structured. Useful for other developers who may want to write LSPs.
+
+### Step 2: Generating BUILD files using BFG binary
+
+TODO(bazel-devel): add explanation and valid example arguments.
+
+```bash
+bazel run //src:bfg <TODO>
+```
+
+### Supported Languages
+
+We currently support Java projects. The next language on our roadmap is Scala.
+
+## Development
+
+### Contributing
+
+We welcome contributions! We generally prefer contributions that either (1) add features by extending BFG to other languages, (2) fix existing bugs, or (3) present bugs through the use of example projects.
 
-## Adding or updating third-party dependencies
+### Dependency Management
 
-We use a third-party tool called [bazel-deps](https://github.com/johnynek/bazel-deps)
-to manage our dependencies. All of our dependencies are listed in
+To manage our dependencies, we use a third-party tool called [bazel-deps](https://github.com/johnynek/bazel-deps). All of our dependencies are listed in
 [`maven_deps.yaml`](maven_deps.yaml). bazel-deps provides tools to manage
 adding and updating dependencies in that file, and generates the Bazel build
 files for them in `thirdparty/jvm/`.

lang/BUILD

@@ -0,0 +1,7 @@
+licenses(["notice"])  # Apache 2.0
+
+java_binary(
+    name = "JavaSourceFileParserCli",
+    main_class = "com.google.devtools.build.bfg.JavaSourceFileParserCli",
+    runtime_deps = ["//lang/java/src/main/java/com/google/devtools/build/bfg:JavaSourceFileParser"],
+)

lang/README.md

@@ -1 +1,16 @@
-A directory for language-specific parsers.
+# Language Specific Parsers
+
+This directory contains a set of language-specific parsers, that can be used to generate a class and file level dependency graph of your project. It outputs this dependency graph as a protobuff. For users of bfg, this dependency graph can be used to generate your BUILD files.
+
+We currently only support Java. However, we plan to add Scala support, and welcome contributions for other languages.
+
+### Usage
+
+```bash
+
+bazel run //lang:JavaSourceFileParserCli 
+
+```
+
+TODO(bazel-devel): what do the command line options mean??? There is a TODO in the Cli asking how the files will be obtained.
+

lang/java/src/main/java/com/google/devtools/build/bfg/BUILD

@@ -30,10 +30,6 @@ java_library(
         "//thirdparty/jvm/com/google/guava",
         "//thirdparty/jvm/org/eclipse/jdt:org_eclipse_jdt_core",
     ],
+    visibility = ["//lang:__subpackages__"],
 )
 
-java_binary(
-    name = "JavaSourceFileParserCli",
-    main_class = "com.google.devtools.build.bfg.JavaSourceFileParserCli",
-    runtime_deps = [":JavaSourceFileParser"],
-)

lang/java/src/main/java/com/google/devtools/build/bfg/JavaSourceFileParserCli.java

@@ -36,8 +36,9 @@
 import protos.com.google.devtools.build.bfg.Bfg;
 
 /**
- * Entry point to BFG java source file parser. Given a list of source files, it prints a graph viz
- * dot file representing the class level dependencies between these source files.
+ * Entry point to the BFG java source file parser. Given a list of source files, 
+ * it obtains the class and file level dependencies between the files, generates a
+ * dependency graph, and outputs this graph as a protobuf.
  */
 public class JavaSourceFileParserCli {
 
@@ -73,7 +74,8 @@ private void run(String[] args) throws Exception {
     } catch (CmdLineException e) {
       if (sourceFiles.isEmpty()) {
         System.err.println("Must provide file names to parse.");
-      } else {
+		//TODO(bazel-team) print example usage of the class
+	  } else {
         System.err.println(e.getMessage());
       }
       e.getParser().printUsage(System.err);

src/BUILD

@@ -0,0 +1,13 @@
+licenses(["notice"])  # Apache 2.0
+
+package(default_visibility = [
+    "//visibility:private",
+])
+
+java_binary(
+    name = "bfg",
+	main_class = "com.google.devtools.build.bfg.Bfg",
+	stamp = 1,
+	runtime_deps = ["//src/main/java/com/google/devtools/build/bfg:Bfg"],
+)
+

src/main/java/com/google/devtools/build/bfg/BUILD

@@ -76,13 +76,9 @@ java_library(
         "//thirdparty/jvm/com/google/guava",
         "//thirdparty/jvm/com/google/re2j",
     ],
-)
-
-java_binary(
-    name = "bfg",
-    main_class = "com.google.devtools.build.bfg.Bfg",
-    stamp = 1,
-    runtime_deps = [":Bfg"],
+    visibility = [
+        "//src:__subpackages__",
+    ],
 )
 
 java_library(

src/main/java/com/google/devtools/build/bfg/Bfg.java

@@ -175,6 +175,7 @@ private static Pattern compilePattern(CmdLineParser cmdLineParser, String patter
     }
   }
 
+  //TODO(bazel-devel): actually print what the intended usage is.
   private static void explainUsageErrorAndExit(CmdLineParser cmdLineParser, String message) {
     System.err.println(message);
     cmdLineParser.printUsage(System.err);