search

jimblandy / DebuggerDocs

Mozilla JavaScript Debugging Documentation
37 stars 12 forks source link

Docs should mention jsdebugger.jsm #1

Open gijsk opened 12 years ago

gijsk commented 12 years ago

As per the summary, it'd be nice if the docs said something about including jsdebugger.jsm, and its location. :-)

Likewise, the remote debugger docs should mention any components one needs there (have not yet looked into using those bits yet).

jimblandy commented 12 years ago

Actually, I think that kind of information belongs in a separate file, "plumbing". Care to submit some text? :)

gijsk commented 12 years ago

That's an interesting idea. Why 'plumbing', though?

I guess to me it comes down to purposes of the document. For me, I use the document because I want to use the API, and the page documents the API. If I want to use the API (nay, before I even can use the API) I need to know about this module (or IJSDebugger, but hey, potato/potayto).

I could certainly understand if you see the purpose of the document differently (maybe as an implementation guide?).

If you don't want this on the page, I think I would suggest creating a page like "Debugging API: Frequently Asked Questions" and then add 'obvious' questions like "Where is this 'Debugger' object?", "How do I get a list of available compartments to debug?", "How do I debug a web worker?", etc.

Does that sound reasonable? It's possible I missed your point, I really have a hard time understanding the 'plumbing' here, sorry! I'll be happy to provide some text once I have an idea who's going to be reading it under what heading. :-)

On 29/03/2012 19:08 PM, jimblandy wrote:

Actually, I think that kind of information belongs in a separate file, "plumbing". Care to submit some text? :)

Reply to this email directly or view it on GitHub: https://github.com/jimblandy/DebuggerDocs/issues/1#issuecomment-4826028

jimblandy commented 12 years ago

You're right, it does come down to the purposes of the document. Up to this point, we've been using it as a specification to implement. It's still evolving, as you know if you watch this git repo. In that role, it's nicer for it to omit descriptions of the plumbing (I was thinking of the "Linux Plumbers Conference" when I used that term).

But now it's just beginning to transition into documentation for users. Certainly, the natural place to find Debugger documentation should also explain how to actually get it going.

I think the first step is to get the plumbing documented at all; I'd like to start that as a separate wiki page.

jimblandy commented 12 years ago

The developers' tools team has just reached the point where things actually run, and we're trying to pull together a demo for a Firefox meeting in late April. Until then, I probably will not be writing surrounding documentation. I'd be happy to answer questions to help you write it, though; find me in #devtools on irc.mozilla.org if you like.

gijsk commented 12 years ago

I'm going to be on holiday until about halfway through April (no internet), so this might languish. I braindumped the gotchas I ran into so far here for now. We can (probably should) move/reformat them, but right now I just wanted to have it written down so as not to forget.

past commented 11 years ago

Just noticed this issue, and I'd like to note that I have created a few wiki pages documenting the Firefox Debugger and the way it uses the remote protocol. I believe the MDN people plan on using them as a starting point for a more thorough documentation. This is the starting page with links to the rest, including the ones in this repo: https://wiki.mozilla.org/Debugger_Architecture