From: José Fonseca Date: Tue, 18 Jun 2013 07:30:28 +0000 (+0100) Subject: Several documentation fixes. X-Git-Url: https://git.cworth.org/git?a=commitdiff_plain;h=ca0b09a5b5b70158f11ddd0d493fd8830d8702f3;p=apitrace Several documentation fixes. --- diff --git a/DEVELOPMENT.markdown b/DEVELOPMENT.markdown index 4a494c2..154b369 100644 --- a/DEVELOPMENT.markdown +++ b/DEVELOPMENT.markdown @@ -1,8 +1,8 @@ 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; @@ -10,8 +10,8 @@ infrastructure to trace generic APIs: * 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. @@ -19,8 +19,8 @@ infrastructure to trace generic APIs: 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. diff --git a/dispatch/README.markdown b/dispatch/README.markdown index d041f7d..b820026 100644 --- a/dispatch/README.markdown +++ b/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. diff --git a/helpers/README.markdown b/helpers/README.markdown index 2f30baa..02ebdfc 100644 --- a/helpers/README.markdown +++ b/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. diff --git a/image/README.markdown b/image/README.markdown index 9236a8f..b290971 100644 --- a/image/README.markdown +++ b/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. diff --git a/retrace/README.markdown b/retrace/README.markdown index 734e8a0..b9120f2 100644 --- a/retrace/README.markdown +++ b/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 diff --git a/specs/README.markdown b/specs/README.markdown index b82672c..812c105 100644 --- a/specs/README.markdown +++ b/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.