[webkit-dev] Comments in the code (Was Please include function-level comments in change log entries)

[Ojan Vafai]

On Wed, Jul 11, 2012 at 8:43 AM, John Mellor <johnme at chromium.org> wrote:

> On Wed, Jul 11, 2012 at 4:21 PM, Ryosuke Niwa <rniwa at webkit.org> wrote:
>
>> On Wed, Jul 11, 2012 at 6:54 AM, John Mellor <johnme at chromium.org> wrote:
>>
>>> 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:
>>>
>>> // An inline box represents a rectangle that occurs on a line,
>>> corresponding to
>>> // all or part of some RenderObject. It must be inline-level and its
>>> contents
>>> // must participate in its containing inline formatting context. For
>>> example a
>>> // non-replaced element with a 'display' value of 'inline' generates an
>>> inline
>>> // box, as does an anonymous inline element (text directly contained
>>> inside a
>>> // block container element, not inside an inline element). But atomic
>>> // inline-level boxes (such as replaced inline-level elements,
>>> inline-block
>>> // elements, inline-table elements, and ruby elements) are not inline
>>> boxes
>>> // since they participate in their inline formatting context as a single
>>> // opaque box; these are handled by <insert class that deals with these>.
>>> // http://www.w3.org/TR/2011/REC-CSS2-20110607/visuren.html#inline-boxes
>>>
>>
>> What's the point of adding this comment when the URL contains all the
>> information?  All we need is the URL.  If anything, we should be describing
>> the difference between the inline boxes in CSS2.1 and our implementation
>> instead.
>>
>
> That would be great! I agree that there's probably limited value in just
> copy/pasting from specs like I did. Linking to the spec something is based
> on and describing the differences would add a lot of value.
>
>
>> Also, with that argument, we can start adding a WHOLE bunch of comments
>> to WebCore like what DOM node is, and what "mutation" means, what "content
>> attribute" is, etc... But we don't do that because we expect people to have
>> some domain-specific knowledge. Of course, I'm not opposed to adding
>> reference URLs as necessary since that'll be actually useful for
>> some obscure concepts.
>>
>
It's also often not obvious if the WebCore object is actually intended to
map to the equivalent CSS/DOM/HTML concept. Sometimes it is and sometimes
it's not. Clearly Attr/Attribute could use a why-style comment for example.


>> - Ryosuke
>>
>>
>
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo/webkit-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120711/e722a1cc/attachment.html>