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

[Ryosuke Niwa]

On Jul 11, 2012 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.

The problem is that we'll then incur the maintenace cost of keeping
comments up-to-date and the risk of them getting out-of-date as we have
previously discussed.

- Ryosuke
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120711/c1a48591/attachment.html>