Breakpad Linux dumper: Add file comments as required by the style guide.

This also includes some comments I promised Cary Coutant I'd write
about the appropriateness of processing attributes in EndAttributes
calls.

The Google C++ Style Guide requires each file to have an author notice
and a comment explaining the file's general purpose. For the record, I
don't think putting an author notice on the files is a good idea; it's
odd to have the original author retain prominence even if the file has
been heavily edited by others; the version control system answers this
question more accurately. This is only for Style Guide compliance. The
Apache group decided to discourage author annotations, partially for
these reasons:

http://mail-archives.apache.org/mod_mbox/jakarta-jmeter-dev/200402.mbox/%3C4039F65E.7020406@atg.com%3E

a=jimblandy, r=nealsid


git-svn-id: http://google-breakpad.googlecode.com/svn/trunk@518 4c0a9323-5329-0410-9bdc-e9ce6186880e

4 files changed, 25 insertions, 2 deletions

diff --git a/src/common/dwarf/dwarf2diehandler.cc b/src/common/dwarf/dwarf2diehandler.cc
index 1998a854..099f5193 100644
--- a/src/common/dwarf/dwarf2diehandler.cc
+++ b/src/common/dwarf/dwarf2diehandler.cc
@@ -26,7 +26,10 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-// Implementation of dwarf2reader::DieDispatcher class.
+// Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
+
+// dwarf2diehandler.cc: Implement the dwarf2reader::DieDispatcher class.
+// See dwarf2diehandler.h for details.
 
 #include <cassert>
 
diff --git a/src/common/dwarf/dwarf2diehandler.h b/src/common/dwarf/dwarf2diehandler.h
index f2985c03..4c9d7536 100644
--- a/src/common/dwarf/dwarf2diehandler.h
+++ b/src/common/dwarf/dwarf2diehandler.h
@@ -28,6 +28,8 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+// Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
+
 // dwarf2reader::CompilationUnit is a simple and direct parser for
 // DWARF data, but its handler interface is not convenient to use.  In
 // particular:
@@ -56,7 +58,7 @@
 //   type DIEs don't.  It would be nice to be able to have separate
 //   handler classes for separate kinds of DIEs, each with the members
 //   appropriate to its role, instead of having one handler class that
-//   needs to hold data for all every DIE type.
+//   needs to hold data for every DIE type.
 //
 // - There should be a separate instance of the appropriate handler
 //   class for each DIE, instead of a single object with tables
@@ -184,6 +186,12 @@ class DIEHandler {
   // same restrictions as the corresponding member functions of
   // dwarf2reader::Dwarf2Handler.
   //
+  // Since DWARF does not specify in what order attributes must
+  // appear, avoid making decisions in these functions that would be
+  // affected by the presence of other attributes. The EndAttributes
+  // function is a more appropriate place for such work, as all the
+  // DIE's attributes have been seen at that point.
+  //
   // The default definitions ignore the values they are passed.
   virtual void ProcessAttributeUnsigned(enum DwarfAttribute attr,
                                         enum DwarfForm form,
@@ -208,6 +216,11 @@ class DIEHandler {
   // child.  If that returns a handler object, we use that to visit
   // the child; otherwise, we skip the child.
   //
+  // This is a good place to make decisions that depend on more than
+  // one attribute. DWARF does not specify in what order attributes
+  // must appear, so only when the EndAttributes function is called
+  // does the handler have a complete picture of the DIE's attributes.
+  //
   // The default definition elects to ignore the DIE's children.
   // You'll need to override this if you override FindChildHandler,
   // but at least the default behavior isn't to pass the children to
diff --git a/src/common/dwarf/dwarf2diehandler_unittest.cc b/src/common/dwarf/dwarf2diehandler_unittest.cc
index 4cfe1117..67ccb95f 100644
--- a/src/common/dwarf/dwarf2diehandler_unittest.cc
+++ b/src/common/dwarf/dwarf2diehandler_unittest.cc
@@ -28,6 +28,10 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+// Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
+
+// dwarf2diehander_unittest.cc: Unit tests for google_breakpad::DIEDispatcher.
+
 #include "breakpad_googletest_includes.h"
 
 #include "common/dwarf/dwarf2diehandler.h"
diff --git a/src/common/dwarf/dwarf2reader.cc b/src/common/dwarf/dwarf2reader.cc
index 028531f4..ec30a309 100644
--- a/src/common/dwarf/dwarf2reader.cc
+++ b/src/common/dwarf/dwarf2reader.cc
@@ -26,6 +26,9 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+// Implementation of dwarf2reader::LineInfo and dwarf2reader::CompilationUnit.
+// See dwarf2reader.h for details.
+
 #include <cassert>
 #include <cstdio>
 #include <cstring>