Several documentation fixes.

DEVELOPMENT.markdown

@@ -1,26 +1,26 @@
 Overview
 =========
 
-Although focus was and still is on graphical APIs, apitrace has an
-infrastructure to trace generic APIs:
+Although focus was and still is on graphical APIs, apitrace has a
+generic infrastructure to trace any kind of API:
 
  * the APIs types and calls are specified in Python files in specs
    sub-directory;
 
    * there is a type hierarchy in specs/stdapi.py, capable of representing
      most types in C language, and additional semantic metadata
 
- * Python scripts generate C code to trace and serialize calls to disk, and
-   vice-versa.
+ * Python scripts generate C++ code to trace and serialize calls parameters to
+   a file, and vice-versa.
 
    * Visitor software design pattern is used to navigate over the types.
 
    * Template design pattern is use so that any step of code generation can be
      overriden by derived classes, allowing to easily handle cases that need
      special treatment without sacrifycing code reuse.
 
-There are several main layers in apitrace.  Too many to show in a single graph,
-so below only those relevant for GL are shown:
+apitrace's architecture is composed of several layers.  Too many to show in a
+single graph, so only those relevant for OpenGL API are shown below:
 
                         specs
                           ^
@@ -43,15 +43,15 @@ so below only those relevant for GL are shown:
            /      |      \
      glxtrace  wgltrace  cgltrace
 
-And here is a quick synopsis of what the layers do:
+Here is a quick synopsis of what the layers do:
 
  * specs -- specification of the API, expressed in a Python class hierarchy
 
  * dispatch -- runtime dispatch of calls to DLLs (open the DLL, get the symbol
    address, and call it passing all arguments as-is)
 
- * helpers -- helper functions to determine sizes of array/blob/etc, and other.
-   It often needs to dispatch calls to give the answers.
+ * helpers -- helper functions to determine sizes of arrays, blobs, etc.  It
+   often needs to dispatch calls to give the answers.
 
  * trace -- generate C++ code for tracing an API based on its spec
 
@@ -75,8 +75,8 @@ And here is a quick synopsis of what the layers do:
 Coding Style
 ============
 
-These are guidelines for new code.  Some of existing hasn't been updated to
-these conventions yet.
+These are guidelines for new code.  Admittedly some of the existing code hasn't
+been updated to follow these conventions yet.
 
 Whitespace (all languages):
 
@@ -156,7 +156,7 @@ Backwards compatibility:
 * No backwards compatibility guarantees for derived data (ASCII dumps, state,
   images, etc).
 
-* There should be no gratuitous change to command line tool interfaces, but no
+* There should be no gratuitous changes to command line tool interfaces, but no
   guarantees are given.
 
 

dispatch/README.markdown

@@ -1,9 +1,9 @@
-The dispatch layer objecting is to get public or private symbols from DLLs /
-shared objects and dispatch calls to them.
+The dispatch layer objective is to resolve the addresses of public and private
+symbols from DLLs / shared objects and dispatch calls to them.
 
 It used both by the tracing wrappers (to dispatch the intercepted calls to
 their true counterparts) and when replaying traces (to dispatch the calls
-recorded on the file)
+recorded on the file).
 
-All code is generated from dispatch.py Python script, which is then used in
-several places.
+Most of the code is generated from dispatch.py script, which is then derived
+for particular APIs.

helpers/README.markdown

@@ -1,5 +1,5 @@
 This directory contains several headers with inline functions that are referred
-in the specs for determining array/sizes.
+by the specs for determining sizes to array, blobs, etc.
 
-These are used both when tracing and replaying so care must be taken not to
-make any assumptions.
+These are relied upon both when tracing and replaying so care must be taken to
+not make any assumptions.

image/README.markdown

@@ -1,2 +1,2 @@
-This directory contains class to represent and manipulate images, in memory or
-disk.
+This directory contains a class to represent and manipulate images, in memory
+or disk.

retrace/README.markdown

@@ -2,8 +2,8 @@ The source for replaying retraces lives in this directory.
 
 There are actually several distinct layers in this directory which should be eventually be split out:
 
- - `*`retrace -- deserialization and interpretation of calls from a trace
+ * retrace -- deserialization and interpretation of calls from a trace
 
- - `*`ws -- windowing system helpers and abstractions
+ * ws -- windowing system helpers and abstractions
 
- - `*`state -- dumping of state into JSON format
+ * state -- dumping of state into JSON format

specs/README.markdown

@@ -3,5 +3,5 @@ hierarchy.
 
 The base classes of this hierarchy are in stdapi.py.
 
-Some of this specifications are (partially) generated from other external
-specifications, by scripts in the scripts subdirectory.
+Some of these specifications are (partially) generated from other external
+specifications, by ad-hoc scripts in the `scripts` subdirectory.