In reviewing patches, I feel like I'm commonly pointing out DOMWindow::frame and Document::frame, etc, can be null in some circumstances. Would it be useful to have a diagram of the major objects (Page, Frame, DOMWindow, Document, etc) somewhere on webkit.org that shows their relation, which links can be null, and which objects change / are preserved during navigation? If so, I'm happy to create this with my current knowledge, and hopefully folks with more experience will add parts that I don't know. What's the best medium to make this easy to update in the future? SVG? ASCII art? Adam
I would find this enormously helpful. I also think there's less risk of it going out of date (compared to most documentation) since the connections between objects and their null characteristics are _very_ entrenched. J On Tue, Aug 11, 2009 at 3:03 PM, Adam Barth <abarth@webkit.org> wrote:
In reviewing patches, I feel like I'm commonly pointing out DOMWindow::frame and Document::frame, etc, can be null in some circumstances. Would it be useful to have a diagram of the major objects (Page, Frame, DOMWindow, Document, etc) somewhere on webkit.org that shows their relation, which links can be null, and which objects change / are preserved during navigation?
If so, I'm happy to create this with my current knowledge, and hopefully folks with more experience will add parts that I don't know. What's the best medium to make this easy to update in the future? SVG? ASCII art?
Adam _______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
On Aug 11, 2009, at 6: 03PM, Adam Barth wrote:
Would it be useful to have a diagram of the major objects (Page, Frame, DOMWindow, Document, etc) somewhere on webkit.org that shows their relation, which links can be null, and which objects change / are preserved during navigation?
I would find this very, very useful to both work with and learn from. As it is I can't find any documentation, other then previous patches and the code itself, about this kind of information. Cheers, Joe
On Aug 11, 2009, at 3:03 PM, Adam Barth wrote:
In reviewing patches, I feel like I'm commonly pointing out DOMWindow::frame and Document::frame, etc, can be null in some circumstances. Would it be useful to have a diagram of the major objects (Page, Frame, DOMWindow, Document, etc) somewhere on webkit.org that shows their relation, which links can be null, and which objects change / are preserved during navigation?
If so, I'm happy to create this with my current knowledge, and hopefully folks with more experience will add parts that I don't know. What's the best medium to make this easy to update in the future? SVG? ASCII art?
It would be useful to make such a diagram. Also hard to make it accurate! I'd be happy to provide information and advice to anyone working on this. I'm not sure what format to use to capture the data. In the abstract, my preference would be a plain text file that could be transformed into diagrams in various chosen formats, but that depends on what kind of data we capture. Regards, Maciej
Didn't we just have a thread about this a couple weeks ago, and decided that it's better if the Compiler checked/documented this sort of thing? Oliver had worked on some classes to enforce null checking iirc... On Tue, Aug 11, 2009 at 3:55 PM, Maciej Stachowiak <mjs@apple.com> wrote:
On Aug 11, 2009, at 3:03 PM, Adam Barth wrote:
In reviewing patches, I feel like I'm commonly pointing out
DOMWindow::frame and Document::frame, etc, can be null in some circumstances. Would it be useful to have a diagram of the major objects (Page, Frame, DOMWindow, Document, etc) somewhere on webkit.org that shows their relation, which links can be null, and which objects change / are preserved during navigation?
If so, I'm happy to create this with my current knowledge, and hopefully folks with more experience will add parts that I don't know. What's the best medium to make this easy to update in the future? SVG? ASCII art?
It would be useful to make such a diagram. Also hard to make it accurate! I'd be happy to provide information and advice to anyone working on this.
I'm not sure what format to use to capture the data. In the abstract, my preference would be a plain text file that could be transformed into diagrams in various chosen formats, but that depends on what kind of data we capture.
Regards, Maciej
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
On Tue, Aug 11, 2009 at 3:59 PM, Eric Seidel <eric@webkit.org> wrote:
Didn't we just have a thread about this a couple weeks ago, and decided that it's better if the Compiler checked/documented this sort of thing? Oliver had worked on some classes to enforce null checking iirc...
This is related but different. It's more about documenting the dependencies and how/when things become null rather than whether they _can_ become null. Speaking of which, is anyone working on that other idea? J
Ok, here's my lame attempt at ASCII art: https://bugs.webkit.org/show_bug.cgi?id=28210 Adam On Tue, Aug 11, 2009 at 3:55 PM, Maciej Stachowiak<mjs@apple.com> wrote:
On Aug 11, 2009, at 3:03 PM, Adam Barth wrote:
In reviewing patches, I feel like I'm commonly pointing out DOMWindow::frame and Document::frame, etc, can be null in some circumstances. Would it be useful to have a diagram of the major objects (Page, Frame, DOMWindow, Document, etc) somewhere on webkit.org that shows their relation, which links can be null, and which objects change / are preserved during navigation?
If so, I'm happy to create this with my current knowledge, and hopefully folks with more experience will add parts that I don't know. What's the best medium to make this easy to update in the future? SVG? ASCII art?
It would be useful to make such a diagram. Also hard to make it accurate! I'd be happy to provide information and advice to anyone working on this.
I'm not sure what format to use to capture the data. In the abstract, my preference would be a plain text file that could be transformed into diagrams in various chosen formats, but that depends on what kind of data we capture.
Regards, Maciej
This is now up on the site: http://webkit.org/coding/major-objects.html It's not linked from anywhere yet. It might be a good idea for a couple of folks to look at it. It reflects my understanding of how things work, which might well be wrong. Adam On Tue, Aug 11, 2009 at 9:41 PM, Adam Barth<abarth@webkit.org> wrote:
Ok, here's my lame attempt at ASCII art:
https://bugs.webkit.org/show_bug.cgi?id=28210
Adam
On Tue, Aug 11, 2009 at 3:55 PM, Maciej Stachowiak<mjs@apple.com> wrote:
On Aug 11, 2009, at 3:03 PM, Adam Barth wrote:
In reviewing patches, I feel like I'm commonly pointing out DOMWindow::frame and Document::frame, etc, can be null in some circumstances. Would it be useful to have a diagram of the major objects (Page, Frame, DOMWindow, Document, etc) somewhere on webkit.org that shows their relation, which links can be null, and which objects change / are preserved during navigation?
If so, I'm happy to create this with my current knowledge, and hopefully folks with more experience will add parts that I don't know. What's the best medium to make this easy to update in the future? SVG? ASCII art?
It would be useful to make such a diagram. Also hard to make it accurate! I'd be happy to provide information and advice to anyone working on this.
I'm not sure what format to use to capture the data. In the abstract, my preference would be a plain text file that could be transformed into diagrams in various chosen formats, but that depends on what kind of data we capture.
Regards, Maciej
2009/8/12 Adam Barth <abarth@webkit.org>:
This is now up on the site:
http://webkit.org/coding/major-objects.html
It's not linked from anywhere yet. It might be a good idea for a couple of folks to look at it. It reflects my understanding of how things work, which might well be wrong.
Ok, it's ASCII art, but hopefully a graphical version would make it more clear which object actually has the pointer to the other object. Or if they always have the connected object pointer on both ends of the relation, it would be nice to mention that in the description. -- Kalle Vahlman, zuh@iki.fi Powered by http://movial.com Interesting stuff at http://sandbox.movial.com See also http://syslog.movial.fi
On Tue, Aug 11, 2009 at 11:06 PM, Kalle Vahlman<kalle.vahlman@gmail.com> wrote:
2009/8/12 Adam Barth <abarth@webkit.org>:
This is now up on the site:
http://webkit.org/coding/major-objects.html
It's not linked from anywhere yet. It might be a good idea for a couple of folks to look at it. It reflects my understanding of how things work, which might well be wrong.
Ok, it's ASCII art, but hopefully a graphical version would make it more clear which object actually has the pointer to the other object. Or if they always have the connected object pointer on both ends of the relation, it would be nice to mention that in the description.
Most of the links are bidirectional. I've tried to indicate the ones that are usually uni-directional by adding arrowheads. In any case, the diagram isn't meant to be a substitute for reading the code. It's meant to help new contributors see the big picture. Adam
Adam Barth wrote:
This is now up on the site:
http://webkit.org/coding/major-objects.html
It's not linked from anywhere yet. It might be a good idea for a couple of folks to look at it. It reflects my understanding of how things work, which might well be wrong.
"NULL after navigation" could be clearer - it suggests that DOMWindow and everything below it only exists if you type the URL, but not if a page is loaded by clicking a link, which can't be true. Does it mean that it's NULL immediately after navigation, while waiting for the load, and is replaced by a valid pointer after loading? Joe
On Wed, Aug 12, 2009 at 4:54 AM, Joe Mason<joe.mason@torchmobile.com> wrote:
Adam Barth wrote:
This is now up on the site:
http://webkit.org/coding/major-objects.html
It's not linked from anywhere yet. It might be a good idea for a couple of folks to look at it. It reflects my understanding of how things work, which might well be wrong.
"NULL after navigation" could be clearer - it suggests that DOMWindow and everything below it only exists if you type the URL, but not if a page is loaded by clicking a link, which can't be true.
Oh, I meant navigate to cover both typing in the location bar and clicking a link. Is there a better word to use for that?
Does it mean that it's NULL immediately after navigation, while waiting for the load, and is replaced by a valid pointer after loading?
I wasn't sure the best way to represent this in the diagram. Typically, the edge becomes null in the "up" direction and replaced with a new object in the "down" direction. If you can think of a nice way to explain this on the page, please file a bug, CC me, and upload a patch. :) Adam
Did this ever get linked from the home page? On Wed, Aug 12, 2009 at 7:07 AM, Adam Barth <abarth@webkit.org> wrote:
On Wed, Aug 12, 2009 at 4:54 AM, Joe Mason<joe.mason@torchmobile.com> wrote:
Adam Barth wrote:
This is now up on the site:
http://webkit.org/coding/major-objects.html
It's not linked from anywhere yet. It might be a good idea for a couple of folks to look at it. It reflects my understanding of how things work, which might well be wrong.
"NULL after navigation" could be clearer - it suggests that DOMWindow and everything below it only exists if you type the URL, but not if a page is loaded by clicking a link, which can't be true.
Oh, I meant navigate to cover both typing in the location bar and clicking a link. Is there a better word to use for that?
Does it mean that it's NULL immediately after navigation, while waiting for the load, and is replaced by a valid pointer after loading?
I wasn't sure the best way to represent this in the diagram. Typically, the edge becomes null in the "up" direction and replaced with a new object in the "down" direction. If you can think of a nice way to explain this on the page, please file a bug, CC me, and upload a patch. :)
Adam _______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
Adam Barth wrote:
If so, I'm happy to create this with my current knowledge, and hopefully folks with more experience will add parts that I don't know. What's the best medium to make this easy to update in the future? SVG? ASCII art?
Sounds very useful. The first tool that springs to mind is graphviz, which can generate output from the same source in about a billion different formats, including SVG, PDF, PostScript, and various raster image formats. (I've only used it a little bit, but I think I can remember enough of the syntax to help out if you need.) Joe
participants (7)
-
Adam Barth
-
Eric Seidel
-
Jeremy Orlow
-
Joe Mason
-
Joseph Pecoraro
-
Kalle Vahlman
-
Maciej Stachowiak