jimblandy
commented
11 years ago Okay, this is looking better. Some last requests:
"To get a list of sources" --- which sources? For the current frame? Any sources that have been loaded before? It's specifically the set of all sources currently loaded in the thread actor's scope - the tab, for tab thread actors, or all of Firefox, for chrome thread actors. GC might make sources disappear. You're the implementor, so you know all this; but put yourself in the shoes of some future devtools hacker wanting to know how to use the protocol, but vague on the details, and help them get oriented.
Note that "will reply" can simply be written "replies"; I think keeping things in the present tense where possible makes the docs more legible.
Also, note that you used the active voice here: "To get a list of sources, the client can send the following packet:" which worked out a lot better than using the passive voice here: "Each source actor can be queried". Use the active voice.
(I have a mixed record remembering to avoid gratuitous use of the future tense and the passive voice, so that doc's not perfect, but I feel it makes a big difference when I do remember.)
Thanks for writing this up!
Because this is a request sent to thread actors, could you put it at an appropriate place in the document structure? If the "sources" packet should only be sent when the thread is paused, then the docs should be some child of "Inspecting Paused Threads", perhaps after "Evaluating source-language expressions". If the packet can come at any time, then perhaps it should be a child of "Interacting with Thread-Like Actors", after "Exiting Threads".
Could you flesh out the introduction a little more? "Send" and "Receive" are a bit terse. See, for example, the description of "Listing Stack Frames". This ought to read like proper documentation, not a summary or a slide.