[(dev time of maintaining comments) + (risk of outdated comments causing bugs X dev time of fixing resulting bugs)] << (dev time gained by more contributors each being more knowledgable)
No? On Wed, Jul 11, 2012 at 8:53 AM, Ryosuke Niwa <rn...@webkit.org> wrote: > > On Jul 11, 2012 8:43 AM, "John Mellor" <joh...@chromium.org> wrote: > > > > On Wed, Jul 11, 2012 at 4:21 PM, Ryosuke Niwa <rn...@webkit.org> wrote: > >> > >> On Wed, Jul 11, 2012 at 6:54 AM, John Mellor <joh...@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 > > _______________________________________________ > webkit-dev mailing list > webkit-dev@lists.webkit.org > http://lists.webkit.org/mailman/listinfo/webkit-dev > >
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo/webkit-dev