fix validation issues.

[oota-llvm.git] / docs / CodingStandards.html

diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html
index fd27985be4919e7592fcbdb5a7e83b86edf6dc63..3a7f8b3d1e9a33fd49c2f90f2ad53c4df070c216 100644 (file)
--- a/docs/CodingStandards.html
+++ b/docs/CodingStandards.html
@@ -122,9 +122,9 @@ documentation is very useful:</p>
 
 <b>File Headers</b>
 
-<p>Every source file should have a header on it that
-describes the basic purpose of the file.  If a file does not have a header, it
-should not be checked into CVS.  Most source trees will probably have a standard
+<p>Every source file should have a header on it that describes the basic 
+purpose of the file.  If a file does not have a header, it should not be 
+checked into Subversion.  Most source trees will probably have a standard
 file header format.  The standard format for the LLVM source tree looks like
 this:</p>
 
@@ -134,8 +134,8 @@ this:</p>
 // 
 //                     The LLVM Compiler Infrastructure
 //
-// This file was developed by the LLVM research group and is distributed under
-// the University of Illinois Open Source License. See LICENSE.TXT for details.
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
 // 
 //===----------------------------------------------------------------------===//
 //
@@ -154,9 +154,9 @@ on the first line, along with a very short description of the purpose of the
 file.  This is important when printing out code and flipping though lots of
 pages.</p>
 
-<p>The next section in the file is a concise note that defines the license that
-the file is released under.  This makes it perfectly clear what terms the source
-code can be distributed under.</p>
+<p>The next section in the file is a concise note that defines the license
+that the file is released under.  This makes it perfectly clear what terms the
+source code can be distributed under and should not be modified in any way.</p>
 
 <p>The main body of the description does not have to be very long in most cases.
 Here it's only two lines.  If an algorithm is being implemented or something
@@ -503,14 +503,15 @@ library. There are two problems with this:</p>
 
 <ol>
   <li>The time to run the static c'tors impacts startup time of
-      applications&mdash;a critical time for gui apps.</li>
+      applications&mdash;a critical time for GUI apps.</li>
   <li>The static c'tors cause the app to pull many extra pages of memory off the
-      disk: both the code for the static c'tors in each .o file and the small
-      amount of data that gets touched.  In addition, touched/dirty pages put
-      more pressure on the VM system on low-memory machines.</li>
+      disk: both the code for the static c'tors in each <tt>.o</tt> file and the
+      small amount of data that gets touched. In addition, touched/dirty pages
+      put more pressure on the VM system on low-memory machines.</li>
 </ol>
 
-<table align="center">
+<div align="center">
+<table>
   <tbody>
     <tr>
       <th>Old Way</th>
@@ -524,7 +525,7 @@ library. There are two problems with this:</p>
       <td align="left"><pre>DEBUG(std::cerr &lt;&lt; ...);
 DEBUG(dump(std::cerr));</pre></td>
       <td align="left"><pre>DOUT &lt;&lt; ...;
-dump(DOUT);</pre></td>
+DEBUG(dump(DOUT));</pre></td>
     </tr>
     <tr>
       <td align="left"><pre>std::cerr &lt;&lt; "Hello world\n";</pre></td>
@@ -551,19 +552,21 @@ dump(DOUT);</pre></td>
       <td align="left"><pre>llvm::StringStream</pre></td>
     </tr>
     <tr>
-      <td align="left"><pre>void print(std::ostream &Out);
+      <td align="left"><pre>void print(std::ostream &amp;Out);
 // ...
 print(std::cerr);</pre></td>
-      <td align="left"><pre>void print(std::ostream &Out);
-void print(std::ostream *Out) { if (Out) print(*Out) }
+      <td align="left"><pre>void print(llvm::OStream Out);<sup>1</sup>
 // ...
 print(llvm::cerr);</pre>
 
-<ul><i>N.B.</i> The second <tt>print</tt> method is called by the <tt>print</tt>
-expression. It prevents the execution of the first <tt>print</tt> method if the
-stream is <tt>cnull</tt>.</ul></td>
-   </tbody>
-</table>
+</td> </tbody> </table>
+</div>
+
+<div class="doc_text">
+<p><sup>1</sup><tt>llvm::OStream</tt> is a light-weight class so it should never
+be passed by reference. This is important because in some configurations,
+<tt>DOUT</tt> is an rvalue.</p>
+</div>
 
 </div>
 
@@ -732,15 +735,12 @@ sources.  Two particularly important books for our work are:</p>
 
 <ol>
 
-<li><a href="http://www.aw-bc.com/catalog/academic/product/0,1144,0201310155,00.html">Effective
-C++</a> by Scott Meyers.  There is an online version of the book (only some
-chapters though) <a
-href="http://www.awlonline.com/cseng/meyerscddemo/">available as well</a>.  Also
+<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
+C++</a> by Scott Meyers.  Also 
 interesting and useful are "More Effective C++" and "Effective STL" by the same
 author.</li>
 
-<li><a href="http://cseng.aw.com/book/0,3828,0201633620,00.html">Large-Scale C++
-Software Design</a> by John Lakos</li>
+<li>Large-Scale C++ Software Design by John Lakos</li>
 
 </ol>