Brief description of the docshell
If you've ever wonder what the docshell is (and who hasn't?!) then you
might find this plain English description helpful.
Big disclaimer
Please note that the docshell is a private object and implements private interfaces. This is useful background information for embedders but you are strongly discouraged from using private interfaces implemented by the docshell. Doing this from an embedding application will break binary compatibility with each release of Mozilla / Gecko and will break your source code from time to time. In other words use the public frozen APIs.
Description
The docshell object is responsible for initiating loading of content from a uri, creating the content viewer and hooking it up to the incoming content. It provides the usual methods for navigation (loaduri, stop, back, forward etc.) as well as managing the session & global history objects. It is basically the glue that holds the front-end and the back end together. As it touches so many areas it gets modified a lot (500 or so checkins), and occasionally suffers from "dumping ground" syndrome where someone inflicts their own coding conventions and useless cruft on the docshell. Generally speaking though the code is pretty generic and the class data is small but there is over 6000 lines of code in the docshell class alone.
The code for the docshell is contained in mozilla/docshell/base/. The docshell class is in nsDocShell.cpp/h with nsDSURIContentListener.cpp used for listening to incoming content. Docshell is used by the chrome, web browsing and the editor. Some webbrowser specific things, such as how to handle page load errors and link clicks is performed by a subclass of the docshell called webshell implemented in nsWebShell.cpp.
Docshells are arranged into a hierarchy - one per content viewer, so that a typical app will contain at least one or two to begin with, one for the primary content area and one for the UI if it is a chrome application. Each tree of docshells is owned by a docshell tree owner which is implemented elsewhere. The tree owner is responsible for destroying the docshells when it is done with them. When a docshell is destroyed or told to load new content it will automatically halt any load in progress, destroy the associated content viewer as any child docshells it has. Docshells may have a name and the class has methods for locating a named docshell elsewhere in the hierarchy.
Each docshell has an item type, either typeContent or typeChrome depending on what they're hosting. The item type is used during traversal to prevent untrusted content from getting hold of chrome documents and for limiting searches on named items. Urls from docshells with a chrome item type are not added to the session history. The item type also affects the script context which is created and associated with a document during loading. The item type is very important for security in other words.
There is also some security code to prevent frameset spoofing, to ensure that content from one domain cannot access children, siblings or parents from another.
The docshell also contains utility methods for obtaining DOM documents, presentation shells from the content viewers, plus miscellaneous code for reporting page load errors to the user, determining whether a document is busy or not (for the busy cursor), and for scrolling to anchors.
The docshell module also contains the URI fixup object. The fixup object is a service responsible for turning a string url into a proper URI object, by correcting typical mistakes made by users when typing, e.g. forgetting to put http:// on the front and so on. The docshell will call the URI fixup object before attempting to load a string url. The webshell can also call the fixup object after a page load error, e.g. to turn http://cnn/ into http://www.cnn.com/ if the former fails.