<div class="gmail_extra">On Fri, Jul 6, 2012 at 11:49 PM, Ryosuke Niwa <span dir="ltr">&lt;<a href="mailto:rniwa@webkit.org" target="_blank">rniwa@webkit.org</a>&gt;</span> wrote: <div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div class="im">On Jul 6, 2012 3:16 PM, &quot;Per Bothner&quot; &lt;<a href="mailto:per.bothner@oracle.com" target="_blank">per.bothner@oracle.com</a>&gt; wrote:<br>
&gt; On 07/06/2012 02:02 PM, Ryosuke Niwa wrote: </div></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">&gt;&gt; On Fri, Jul 6, 2012 at 12:54 PM, Per Bothner &lt;<a href="mailto:per.bothner@oracle.com">per.bothner@oracle.com</a>&gt; wrote:</div>

</blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">&gt;&gt;&gt; You&#39;re deluding yourself if you think the code (or any code this </div></blockquote>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">&gt;&gt;&gt; large and complicated) is or can be self-evident. </div></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div class="im">&gt;&gt; </div></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">&gt;&gt; That&#39;s a pretty strong claim. I find that the vast majority of codebase </div>

</blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">&gt;&gt; to be quite self-evident. </div></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div class="im">&gt; </div></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">&gt; If you (who I gather has quite a bit of WebKit experience) find something </div>

</blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">&gt; self-evident, does not mean it is is.</div><p>To be fair, as I said, I was able to read WebKit code without much trouble 2-3 months into my internship. I&#39;m not sympathetic to people who can&#39;t read code as well as an undergraduate college student.</p>


<p>Also, we need require some kind of prior knowledge of things. For example, InlineBox might be a foreign concept to you but it&#39;s plain dead obvious for anyone who has read CSS2.1 specifications.</p>
<p>Similarly, there might be some classes that are self-explanatory for someone who knows ES5 well and confusing for someone who is not.</p>
<p>Where should we draw a line then?</p></blockquote><div><div>Even obvious (to some) concepts like InlineBox have subtleties, for example not all inline-level elements have inline boxes. An unambiguous class-level comment could make this clearer, for example:</div>

<div><br></div><div>// An inline box represents a rectangle that occurs on a line, corresponding to</div><div>// all or part of some RenderObject. It must be inline-level and its contents</div><div>// must participate in its containing inline formatting context. For example a</div>

<div>// non-replaced element with a &#39;display&#39; value of &#39;inline&#39; generates an inline</div><div>// box, as does an anonymous inline element (text directly contained inside a</div><div>// block container element, not inside an inline element). But atomic</div>

<div>// inline-level boxes (such as replaced inline-level elements, inline-block</div><div>// elements, inline-table elements, and ruby elements) are not inline boxes</div><div>// since they participate in their inline formatting context as a single</div>

<div>// opaque box; these are handled by &lt;insert class that deals with these&gt;.</div><div>// <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/visuren.html#inline-boxes">http://www.w3.org/TR/2011/REC-CSS2-20110607/visuren.html#inline-boxes</a></div>

<div><br></div><div>Some may find that too verbose. But at least a link to the relevant part of the spec would be a good start...</div></div></div></div>