Add a few comments to the code.

webrender/src/frame.rs

@@ -55,6 +55,7 @@ struct FlattenInfo {
 
 pub type LayerMap = HashMap<ScrollLayerId, Layer, BuildHasherDefault<FnvHasher>>;
 
+// TODO: doc
 pub struct Frame {
     pub layers: LayerMap,
     pub pipeline_epoch_map: HashMap<PipelineId, Epoch, BuildHasherDefault<FnvHasher>>,
@@ -525,6 +526,17 @@ impl Frame {
                                    &composition_operations);
 
         if level == 0 {
+            // Add a large white rectangle as the root display item. This is removed
+            // by the occlusion culling for most tiles, and means that it's no longer
+            // necessary to clear the framebuffer.
+            //
+            // TODO(nical) Should this be optional?
+            // on deferred GPUs we probably still want to clear the framebuffer and
+            // Gecko currently supports semit-transparent windows.
+            // Also, this is not needed if the root stacking context has an opaque
+            // background (specified in set_root_stacking_context).
+            //
+            // If we do need this, does it make sense to keep Frame::clear_tiles?
             context.builder.add_solid_rectangle(&stacking_context.bounds,
                                                 &stacking_context.bounds,
                                                 None,

webrender/src/gpu_store.rs

@@ -8,6 +8,7 @@ use std::mem;
 #[derive(Debug, Copy, Clone)]
 pub struct GpuStoreAddress(pub i32);
 
+/// A CPU-side buffer storing content to be uploaded to the GPU.
 pub struct GpuStore<T> {
     data: Vec<T>,
     // TODO(gw): Could store this intrusively inside

webrender/src/internal_types.rs

@@ -354,9 +354,15 @@ impl TextureUpdateList {
     }
 }
 
+/// Mostly wraps a tiling::Frame, adding a bit of extra information.
 pub struct RendererFrame {
+    /// The last rendered epoch for each pipeline present in the frame.
+    /// This information is used to know if a certain transformation on the layout has
+    /// been rendered, which is necessary for reftests.
     pub pipeline_epoch_map: HashMap<PipelineId, Epoch, BuildHasherDefault<FnvHasher>>,
+    /// The layers that are currently affected by the over-scrolling animation.
     pub layers_bouncing_back: HashSet<ScrollLayerId, BuildHasherDefault<FnvHasher>>,
+
     pub frame: Option<tiling::Frame>,
 }
 

webrender/src/layer.rs

@@ -6,32 +6,33 @@ use euclid::{Matrix4D, Point2D, Rect, Size2D};
 use spring::{DAMPING, STIFFNESS, Spring};
 use webrender_traits::{PipelineId, ScrollLayerId};
 
+/// Contains scroll and transform information for scrollable and root stacking contexts.
 pub struct Layer {
-    // Manages scrolling offset, overscroll state etc.
+    /// Manages scrolling offset, overscroll state etc.
     pub scrolling: ScrollingState,
 
-    // Size of the content inside the scroll region (in logical pixels)
+    /// Size of the content inside the scroll region (in logical pixels)
     pub content_size: Size2D<f32>,
 
-    // Viewing rectangle
+    /// Viewing rectangle
     pub local_viewport_rect: Rect<f32>,
 
-    // Viewing rectangle clipped against parent layer(s)
+    /// Viewing rectangle clipped against parent layer(s)
     pub combined_local_viewport_rect: Rect<f32>,
 
-    // World transform for the viewport rect itself.
+    /// World transform for the viewport rect itself.
     pub world_viewport_transform: Matrix4D<f32>,
 
-    // World transform for content within this layer
+    /// World transform for content within this layer
     pub world_content_transform: Matrix4D<f32>,
 
-    // Transform for this layer, relative to parent layer.
+    /// Transform for this layer, relative to parent layer.
     pub local_transform: Matrix4D<f32>,
 
-    // Pipeline that this layer belongs to
+    /// Pipeline that this layer belongs to
     pub pipeline_id: PipelineId,
 
-    // Child layers
+    /// Child layers
     pub children: Vec<ScrollLayerId>,
 }
 

webrender/src/prim_store.rs

@@ -40,6 +40,7 @@ pub enum PrimitiveKind {
     BoxShadow,
 }
 
+/// Geometry description for simple rectangular primitives, uploaded to the GPU.
 #[derive(Debug, Clone)]
 pub struct PrimitiveGeometry {
     pub local_rect: Rect<f32>,

webrender/src/render_backend.rs

@@ -23,7 +23,10 @@ use record;
 use tiling::FrameBuilderConfig;
 use offscreen_gl_context::GLContextDispatcher;
 
-
+/// The render backend is responsible for transforming high level display lists into
+/// GPU-friendly work which is then submitted to the renderer in the form of a frame::Frame.
+///
+/// The render backend operates on its own thread.
 pub struct RenderBackend {
     api_rx: IpcReceiver<ApiMsg>,
     payload_rx: IpcBytesReceiver,

webrender/src/renderer.rs

@@ -310,6 +310,8 @@ fn create_clear_shader(name: &'static str,
     program_id
 }
 
+/// The renderer is responsible for submitting to the GPU the work prepared by the
+/// RenderBackend.
 pub struct Renderer {
     result_rx: Receiver<ResultMsg>,
     device: Device,

webrender/src/scene.rs

@@ -14,6 +14,7 @@ use webrender_traits::{SpecificDisplayListItem};
 use webrender_traits::{IframeInfo};
 use webrender_traits::{RectangleDisplayItem, ClipRegion, DisplayItem, SpecificDisplayItem};
 
+/// A representation of the layout within the display port for a given document or iframe.
 #[derive(Debug)]
 pub struct ScenePipeline {
     pub pipeline_id: PipelineId,
@@ -23,6 +24,7 @@ pub struct ScenePipeline {
     pub viewport_size: Size2D<f32>,
 }
 
+/// A complete representation of the layout bundling visible pipelines together.
 pub struct Scene {
     pub root_pipeline_id: Option<PipelineId>,
     pub pipeline_map: HashMap<PipelineId, ScenePipeline, BuildHasherDefault<FnvHasher>>,
@@ -46,6 +48,7 @@ pub struct SceneItem {
     pub specific: SpecificSceneItem,
 }
 
+/// Similar to webrender_traits::DisplayList internal to WebRender.
 pub struct SceneDisplayList {
     pub pipeline_id: PipelineId,
     pub epoch: Epoch,

webrender/src/tiling.rs

@@ -348,6 +348,7 @@ struct AlphaBatchTask {
     items: Vec<AlphaRenderItem>,
 }
 
+/// Encapsulates the logic of building batches for items that are blended.
 pub struct AlphaBatcher {
     pub batches: Vec<PrimitiveBatch>,
     tasks: Vec<AlphaBatchTask>,
@@ -473,6 +474,7 @@ struct RenderTargetContext<'a> {
     render_task_id_counter: AtomicUsize,
 }
 
+/// A render target represents a number of rendering operations on a surface.
 pub struct RenderTarget {
     pub alpha_batcher: AlphaBatcher,
     pub box_shadow_cache_prims: Vec<CachePrimitiveInstance>,
@@ -529,6 +531,11 @@ impl RenderTarget {
     }
 }
 
+/// A render pass represents a set of rendering operations that don't depend on one
+/// another.
+///
+/// A render pass can have several render targets if there wasn't enough space in one
+/// target to do all of the rendering for that pass.
 pub struct RenderPass {
     pass_index: RenderPassIndex,
     pub is_framebuffer: bool,
@@ -1177,6 +1184,8 @@ pub struct FrameBuilder {
     scrollbar_prims: Vec<ScrollbarPrimitive>,
 }
 
+/// A rendering-oriented representation of frame::Frame built by the render backend
+/// and presented to the renderer.
 pub struct Frame {
     pub viewport_size: Size2D<i32>,
     pub debug_rects: Vec<DebugRect>,
@@ -1197,6 +1206,7 @@ pub struct Frame {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub struct ScreenTileIndex(usize);
 
+/// Some extra per-tile information stored for debugging purposes.
 #[derive(Debug)]
 enum CompiledScreenTileInfo {
     SimpleAlpha(usize),
@@ -1356,6 +1366,8 @@ impl ScreenTile {
 
                         let prim_bounding_rect = ctx.prim_store.get_bounding_rect(prim_index);
 
+                        // If an opaque primitive covers a tile entirely, we can discard
+                        // all primitives underneath it.
                         if layer.xf_rect.as_ref().unwrap().kind == TransformedRectKind::AxisAligned &&
                            prim_metadata.clip_index.is_none() &&
                            prim_metadata.is_opaque &&
@@ -1784,6 +1796,8 @@ impl FrameBuilder {
                            PrimitiveContainer::Image(prim_cpu));
     }
 
+    /// Compute the contribution (bounding rectangles, and resources) of layers and their
+    /// primitives in screen space.
     fn cull_layers(&mut self,
                    screen_rect: &DeviceRect,
                    layer_map: &HashMap<ScrollLayerId, Layer, BuildHasherDefault<FnvHasher>>,