Writing chrome code documentation plan

We currently have sparse, out-of-date, and vague documentation about the ins and outs of writing privileged code on Gecko. We need a good guide to writing chrome JavaScript code. This plan proposes a project to produce that documentation.

Team

wbamberg

Primary writer.

sheppy

Assisting as available/needed.

Goals

• Move existing documentation into the proper places in the content hierarchy, getting rid of anything too out of date to reuse.
• Add an introduction to chrome code
• Improve and add content about wrappers and how they work.
• Provide documentation that explains Gecko-specific knowledge that newcomers to Gecko/XPCOM development will not understand; there's currently no resource for this other than the source code.

Audience

The target audience for this documentation is:

• Add-on developers
• Dev tool developers
• Gecko/Firefox developers

Target milestones

We need to device appropriate milestones for this project, then file bugs for each. These bugs should each block bug 1050934, which is this project's tracking bug.

User stories

• I want to write a Firefox add-on but don't know how to interact with Web content.
• I want to start working on core Gecko or Firefox code but have no idea how this stuff works!
• I'm working on an in-browser developer tool and need to be able to examine or manipulate Web content from within my tool.

Documents needed

The lists here detail specific types of content that need to be produced, as well as precise pages that we know need to be produced or updated.

Types of pages

The following types of pages will need to be produced.

• Reference
  • Interfaces
  • Properties
  • Methods
  • Events
• Guides/tutorials
• Sample code

Reference page work needed

• ???

User guide work needed

• New guide: Writing chrome code
  • Intro: What's chrome code?
    • Various JavaScript contexts in Gecko: chrome (privileged code), content, and sandboxes
  • What's available in the chrome environment?
    • Components
      • Classes
      • XPCOM
      • JavaScript code modules (JSMs)
      • Components.utils
    • gBrowser
    • etc.
  • Working with content
    • Getting access to content
    • Using message managers in multiprocess Firefox (e10s)
    • Using service workers (eventually, once they stabilize)
  • Security
    • Compartments
    • X-Ray vision
    • Security principles

References

Existing content

Other notes

wbamberg has been working with Bobby Holley and Gabor Krizsanits on the security and X-ray stuff, and Bill McCloskey on e10s. We should get other Firefox platform people involved in figuring out what else to do here.