Remove cfg(not(test))s from servo/main.rs

Reorganize servo directory code top-down and add comments
Remove cfg(not(test)) from servo/lib.rs
Remove redundant thread from constellation setup

ports/gonk/src/lib.rs

@@ -66,16 +66,37 @@ pub struct Browser {
     compositor: Box<CompositorEventListener + 'static>,
 }
 
+/// The in-process interface to Servo.
+///
+/// It does everything necessary to render the web, primarily
+/// orchestrating the interaction between JavaScript, CSS layout,
+/// rendering, and the client window.
+///
+/// Clients create a `Browser` for a given reference-counted type
+/// implementing `WindowMethods`, which is the bridge to whatever
+/// application Servo is embedded in. Clients then create an event
+/// loop to pump messages between the embedding application and
+/// various browser components.
 impl Browser {
     #[cfg(not(test))]
     pub fn new<Window>(window: Option<Rc<Window>>) -> Browser
         where Window: WindowMethods + 'static {
         ::util::opts::set_experimental_enabled(opts::get().enable_experimental);
+        // Global configuration options, parsed from the command line.
         let opts = opts::get();
+
+        // Create the global vtables used by the (generated) DOM
+        // bindings to implement JS proxies.
         RegisterBindings::RegisterProxyHandlers();
 
+        // Use this thread pool to load-balance simple tasks, such as
+        // image decoding.
         let shared_task_pool = TaskPool::new(8);
 
+        // Get both endpoints of a special channel for communication between
+        // the client window and the compositor. This channel is unique because
+        // messages to client may need to pump a platform-specific event loop
+        // to deliver the message.
         let (compositor_proxy, compositor_receiver) =
             WindowMethods::create_compositor_channel(&window);
         let time_profiler_chan = time::Profiler::create(opts.time_profiler_period);
@@ -100,6 +121,10 @@ impl Browser {
 
         let font_cache_task = FontCacheTask::new(resource_task.clone());
         let storage_task = StorageTaskFactory::new();
+
+        // Create the constellation, which maintains the engine
+        // pipelines, including the script and layout threads, as well
+        // as the navigation context.
         let constellation_chan = Constellation::<layout::layout_task::LayoutTask,
                                                  script::script_task::ScriptTask>::start(
                                                       compositor_proxy.clone_compositor_proxy(),
@@ -123,6 +148,8 @@ impl Browser {
         let ConstellationChan(ref chan) = constellation_chan;
         chan.send(ConstellationMsg::InitLoadUrl(url)).unwrap();
 
+        // The compositor coordinates with the client window to create the final
+        // rendered page and display it somewhere.
         let compositor = CompositorTask::create(window,
                                                 compositor_proxy,
                                                 compositor_receiver,

ports/gonk/src/main.rs

@@ -11,6 +11,19 @@
 // For FFI
 #![allow(non_snake_case, dead_code)]
 
+//! The `servo` test application.
+//!
+//! Creates a `Browser` instance with a simple implementation of
+//! the compositor's `WindowMethods` to create a working web browser.
+//!
+//! This browser's implementation of `WindowMethods` is built on top
+//! of [glutin], the cross-platform OpenGL utility and windowing
+//! library.
+//!
+//! For the engine itself look next door in lib.rs.
+//!
+//! [glutin]: https://github.com/tomaka/glutin
+
 extern crate servo;
 extern crate time;
 extern crate util;
@@ -42,6 +55,7 @@ struct BrowserWrapper {
 }
 
 fn main() {
+    // Parse the command line options and store them globally
     if opts::from_cmdline_args(env::args().collect::<Vec<_>>().as_slice()) {
         resource_task::global_init();
 
@@ -51,6 +65,8 @@ fn main() {
             Some(window::Window::new())
         };
 
+        // Our wrapper around `Browser` that also implements some
+        // callbacks required by the glutin window implementation.
         let mut browser = BrowserWrapper {
             browser: Browser::new(window.clone()),
         };
@@ -62,6 +78,8 @@ fn main() {
 
         browser.browser.handle_event(WindowEvent::InitializeCompositing);
 
+        // Feed events from the window to the browser until the browser
+        // says to stop.
         loop {
             let should_continue = match window {
                 None => browser.browser.handle_event(WindowEvent::Idle),