From: José Fonseca <jfonseca@vmware.com>
Date: Tue, 30 Nov 2010 16:58:22 +0000 (+0000)
Subject: Add brief comments.
X-Git-Url: https://git.cworth.org/git?a=commitdiff_plain;h=4a826ed267c580a0f5e803ff7f05710c9d135b70;p=apitrace

Add brief comments.
---

diff --git a/TODO b/TODO
index d33f275..e1665fe 100644
--- a/TODO
+++ b/TODO
@@ -33,3 +33,5 @@
 * Write snapshots as PNGs instead of BMPs
 
 * Add new mode to compare with previous snapshots instead of writing.
+
+* Plug memory leaks.
diff --git a/bmp.hpp b/bmp.hpp
index 872bc75..b6a4ab7 100644
--- a/bmp.hpp
+++ b/bmp.hpp
@@ -23,6 +23,10 @@
  *
  **************************************************************************/
 
+/*
+ * BMP image writing.
+ */
+
 #ifndef _BMP_HPP_
 #define _BMP_HPP_
 
diff --git a/codegen.py b/codegen.py
index 2aff635..4a6405d 100644
--- a/codegen.py
+++ b/codegen.py
@@ -24,6 +24,9 @@
 ##########################################################################/
 
 
+"""C code generation helpers."""
+
+
 def _string_switch(var, prefix, suffixes, case, default):
     index = len(prefix)
     indent = '    '*(index + 1)
@@ -72,6 +75,7 @@ def _noop(*args, **kwargs):
 
 
 def string_switch(var, values, case=_noop, default=None):
+    """Product a switch of strings, using a tree character switches."""
     values = list(values)
     values.sort()
     _string_switch(var, '', values, case, default)
diff --git a/compat.h b/compat.h
index d49955b..e98f746 100644
--- a/compat.h
+++ b/compat.h
@@ -25,6 +25,10 @@
  *
  **************************************************************************/
 
+/*
+ * MinGW compatability macros to allow using recent's DXSDK headers.
+ */
+
 #ifdef __MINGW32__
 #define __in /**/
 #define __out /**/
diff --git a/dump.cpp b/dump.cpp
index 5cd28a5..5e85195 100644
--- a/dump.cpp
+++ b/dump.cpp
@@ -24,6 +24,11 @@
  **************************************************************************/
 
 
+/*
+ * Simple utility to dump a trace to standard output.
+ */
+
+
 #include "trace_parser.hpp"
 
 
diff --git a/formatter.hpp b/formatter.hpp
index 3c9db3c..9f17c00 100644
--- a/formatter.hpp
+++ b/formatter.hpp
@@ -23,6 +23,10 @@
  *
  **************************************************************************/
 
+/*
+ * Helpers for coloring output.
+ */
+
 #ifndef _FORMATTER_HPP_
 #define _FORMATTER_HPP_
 
diff --git a/glapi.py b/glapi.py
index b1f3508..8afb411 100644
--- a/glapi.py
+++ b/glapi.py
@@ -24,6 +24,15 @@
 ##########################################################################/
 
 
+"""GL API description.
+
+Most of these were automatically generated with the apigen/glspec.py script
+from Khronos OpenGL spec files, and then manually edited to cover the corner
+cases correctly.
+
+"""
+
+
 from stdapi import *
 from glenum import *
 
diff --git a/glenum.py b/glenum.py
index 8844c8f..58d82b1 100644
--- a/glenum.py
+++ b/glenum.py
@@ -24,6 +24,14 @@
 ##########################################################################/
 
 
+"""GLenum description.
+
+This was semi-automatically generated from glext headers, with vim.  An
+automated procedure to generate it would be nice.
+
+"""
+
+
 from stdapi import *
 
 
diff --git a/glimports.hpp b/glimports.hpp
index 46c8069..e8d2c5c 100644
--- a/glimports.hpp
+++ b/glimports.hpp
@@ -23,6 +23,10 @@
  *
  **************************************************************************/
 
+/*
+ * Central place for all GL includes, and respective OS dependent headers.
+ */
+
 #ifndef _GLIMPORTS_HPP_
 #define _GLIMPORTS_HPP_
 
diff --git a/glproc.py b/glproc.py
index c2e5ffc..3945ab6 100644
--- a/glproc.py
+++ b/glproc.py
@@ -24,6 +24,11 @@
 ##########################################################################/
 
 
+"""Generated an header, glproc.hpp, which does pretty much what GLEW does, but
+covers all the functions we support.
+""" 
+
+
 import stdapi
 from glapi import glapi
 from glxapi import glxapi
diff --git a/glretrace.py b/glretrace.py
index 2b41f1d..d397a90 100644
--- a/glretrace.py
+++ b/glretrace.py
@@ -24,6 +24,9 @@
 ##########################################################################/
 
 
+"""GL retracer generator."""
+
+
 import stdapi
 import glapi
 from retrace import Retracer
diff --git a/glsize.hpp b/glsize.hpp
index ce20488..ead293b 100644
--- a/glsize.hpp
+++ b/glsize.hpp
@@ -26,6 +26,15 @@
  *
  **************************************************************************/
 
+/*
+ * Auxiliary functions to compute the size of array/blob arguments, depending.
+ *
+ * Some of these functions were semi-automatically generated with
+ * apigen/glsize.py script from Mesa's XML description of the GL enums.
+ *
+ * Other functions were done by hand.
+ */
+
 #ifndef _GL_HELPERS_HPP_
 #define _GL_HELPERS_HPP_
 
diff --git a/glxapi.py b/glxapi.py
index 2c853df..a99fbd0 100644
--- a/glxapi.py
+++ b/glxapi.py
@@ -23,6 +23,8 @@
 #
 ##########################################################################/
 
+"""GLX API description."""
+
 
 from stdapi import *
 from glapi import glapi
@@ -55,7 +57,9 @@ PROC = Opaque("__GLXextFuncPtr")
 glxapi.add_functions(glapi.functions)
 glxapi.add_functions([
     Function(GLXContext, "glXCreateContext", [(Display, "dpy"), (Pointer(XVisualInfo), "vis"), (GLXContext, "shareList"), (Bool_, "direct")]),
+    # TODO: the rest
 
+    # Must be last
     Function(PROC, "glXGetProcAddressARB", [(Alias("const GLubyte *", CString), "procName")]),
     Function(PROC, "glXGetProcAddress", [(Alias("const GLubyte *", CString), "procName")]),
 ])
diff --git a/glxtrace.py b/glxtrace.py
index 67ce552..2759319 100644
--- a/glxtrace.py
+++ b/glxtrace.py
@@ -24,6 +24,9 @@
 ##########################################################################/
 
 
+"""GLX tracing generator."""
+
+
 from glxapi import glxapi
 from trace import Tracer
 
diff --git a/os.hpp b/os.hpp
index dbe8deb..eb5d842 100644
--- a/os.hpp
+++ b/os.hpp
@@ -23,6 +23,10 @@
  *
  **************************************************************************/
 
+/*
+ * Simple OS abstraction layer.
+ */
+
 #ifndef _OS_HPP_
 #define _OS_HPP_
 
diff --git a/retrace.py b/retrace.py
index b1e72fd..5326457 100644
--- a/retrace.py
+++ b/retrace.py
@@ -24,6 +24,8 @@
 ##########################################################################/
 
 
+"""Generic retracing code generator."""
+
 import stdapi
 import glapi
 from codegen import *
diff --git a/trace_format.hpp b/trace_format.hpp
index 688c65a..ba57a51 100644
--- a/trace_format.hpp
+++ b/trace_format.hpp
@@ -23,6 +23,10 @@
  *
  **************************************************************************/
 
+/*
+ * Binary trace format decription.
+ */
+
 #ifndef _TRACE_FORMAT_HPP_
 #define _TRACE_FORMAT_HPP_
 
@@ -61,6 +65,8 @@ enum Type {
 };
 
 /*
+ * XXX: Update grammar.
+ *
  * trace = call* EOF
  *
  * call = name (detail)* END
diff --git a/trace_model.hpp b/trace_model.hpp
index e2c0519..f57dc91 100644
--- a/trace_model.hpp
+++ b/trace_model.hpp
@@ -23,6 +23,10 @@
  *
  **************************************************************************/
 
+/*
+ * Object hierarchy for describing the traces in memory.
+ */
+
 #ifndef _TRACE_MODEL_HPP_
 #define _TRACE_MODEL_HPP_
 
diff --git a/trace_write.hpp b/trace_write.hpp
index ca4addc..1dfa463 100644
--- a/trace_write.hpp
+++ b/trace_write.hpp
@@ -23,6 +23,10 @@
  *
  **************************************************************************/
 
+/*
+ * Trace writing functions.
+ */
+
 #ifndef _TRACE_WRITE_HPP_
 #define _TRACE_WRITE_HPP_
 
diff --git a/wglapi.py b/wglapi.py
index 4df7b51..b802362 100644
--- a/wglapi.py
+++ b/wglapi.py
@@ -24,6 +24,9 @@
 ##########################################################################/
 
 
+"""WGL API description"""
+
+
 from glapi import *
 from winapi import *
 
diff --git a/wgltrace.py b/wgltrace.py
index 6474755..7dcb850 100644
--- a/wgltrace.py
+++ b/wgltrace.py
@@ -24,6 +24,9 @@
 ##########################################################################/
 
 
+"""WGL tracing code generator."""
+
+
 from wglapi import wglapi
 from trace import Tracer
 from codegen import *