[PATCH] D26374: Add documentation for the PDB file format

[Adrian McCarthy via llvm-commits]

amccarth added a comment.

I've noted a couple of nits and possibilities for clarifications, but a nice start.  Thanks for writing this.



================
Comment at: docs/PDB/MsfFile.rst:49
+- **BlockMapAddr** - The index of a block within the MSF file.  At this block is
+  an array of ``ulittle32_t``'s describing the layout of the Stream Directory.
+  For large MSF files, the stream directory (which describes the block layout of
----------------
Wording nit:  "describing the layout of the Stream Directory" doesn't seem to capture what I think you mean.  How about "listing the blocks that contain the Stream Directory"?


================
Comment at: docs/PDB/MsfFile.rst:55
+  be stitched together accordingly.  The number of ``ulittle32_t``'s in this array
+  is given by ``⌈NumDirectoryBytes / BlockSize⌉``.
+  
----------------
Did you mean ``[NumDirectoryBytes / 4]``?


================
Comment at: docs/PDB/MsfFile.rst:56
+  is given by ``⌈NumDirectoryBytes / BlockSize⌉``.
+  
+The Stream Directory
----------------
I assume the space between the header and the next block is just 0-filled padding?


================
Comment at: docs/PDB/index.rst:17
+PDBs even without the user understanding the internals of the file format, a
+large ecosystem of tools have been built for Windows to consume this format.  In
+order for Clang to be able to generate programs that can interoperate with these
----------------
grammar nit:  s/have/has/ because "ecosystem" is singular.


================
Comment at: docs/PDB/index.rst:24
+is necessary for us to understand the PDB file format at the byte-level so that
+we can generate PDB files with entirely on our own.
+
----------------
delete "with"


https://reviews.llvm.org/D26374