what exactly document-ready means in jquery

Question

Let us say I have a HTML page that contains a javascript file:

The base.js is like this:

$(document).ready(function () {
   obj.init();
}

// ..............

var obj = {...};

Surprisingly, sometimes(not all the time) Firebug shows me the undefined error on obj.init() call! My understanding is that document ready means all html elements, including images, javascript files downloaded and executed(?).

I believe in order to find the root cause of this error, we need understand what exactly the "document ready" means? anybody has any insight?

============================

Update: maybe I should not mention about image over here, my main concern is regarding the javascript file in particular. Does "DOM fully constructed" include "all javascript code executed"?

============================

Update again: It seems people here agreed that event "document.ready" WILL NOT be triggered until ALL javascript code got downloaded and executed. Thus, root cause of the issue remain unknown. I did bypassed this issue after I moved the $(document).ready block to the bottom of the javascript file.

Answer 1

From the documentation of jQuery.ready():

While JavaScript provides the load event for executing code when a page is rendered, this event does not get triggered until all assets such as images have been completely received. In most cases, the script can be run as soon as the DOM hierarchy has been fully constructed. The handler passed to .ready() is guaranteed to be executed after the DOM is ready, so this is usually the best place to attach all other event handlers and run other jQuery code. When using scripts that rely on the value of CSS style properties, it's important to reference external stylesheets or embed style elements before referencing the scripts.

In cases where code relies on loaded assets (for example, if the dimensions of an image are required), the code should be placed in a handler for the load event instead.