2011/1/31 Konstantin Tokarev <annu...@yandex.ru> > > You can document A as function calling B, B as function calling C, and keep > documentation of C up to date when it's behavior changes >
I don't see how that can substitute my comment that "Because A does X, do Y". Saying "do Y because we call A" isn't useful at all here. But if A is API function, its behavior (what C does) should be described in > place anyway > Okay, let me give you a more concrete example. In this case: http://trac.webkit.org/browser/trunk/WebCore/editing/IndentOutdentCommand.cpp?rev=41034#L79 we're working around an issue in moveParagraph: http://trac.webkit.org/browser/trunk/WebCore/editing/CompositeEditCommand.cpp?rev=41034#L737 Now, moveParagraph is a very complicated function that does a million of things depending on the structure of DOM and 5 arguments, and it's mutually recursive with 2 other editing commands ReplaceSelectionCommand and DeleteSelectionCommand, both of which depend on many other editing commands and the rest of WebCore. As a result, it's virtually impossible to describe the complete behavior of moveParagraph. And if we changed any one line in WebCore/editing, there is a significant chance that we're changing the behavior of either ReplaceSelectionCommand or DeleteSelectionCommand and subsequently, moveParagraph. This is just a tip of an iceberg. I can give you hundreds of examples where you can't describe the behavior of a function completely, and yet you need to be concerned with it in call sites. - Ryosuke
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
