--- a/src/hbutils/document/hbdocumentloader.cpp	Tue Jul 06 14:36:53 2010 +0300
+++ b/src/hbutils/document/hbdocumentloader.cpp	Wed Aug 18 10:05:37 2010 +0300
@@ -97,9 +97,28 @@
 }
 
 /*!
-    Loads and processes DocML file. If After processing of file was successful,
-    it returnes root objects list as a return parameter. Otherwise returnes empty list. 
-    Qwnership to loaded objects is passed to the caller.
+    Loads and processes DocML file. 
+
+    On successful execution, returns a list of root objects. This list contains 
+    only the objects which do not have an owner already e.g. child of a parent 
+    widget is never returned, and the parent is only returned if it does not 
+    have its own parent or some specific role like menu-role. The document 
+    loader instance does not own any of the objects: the ones which do not 
+    have any other owner are returned within the root object list. The caller 
+    is resposible of handling the lifetime of the returned objects.
+
+    Usually this returns the view or the dialog which the loaded DocML defines. 
+
+    There are also situations, when this returns an empty list. These cases 
+    usually include sections, which change the existing properties and do not 
+    create any new root objects. Also, the items passed with setObjectTree() 
+    function are not returned. So, the success of the load() cannot be
+    deternimed directly by the number of the returned objects. This is what
+    the parameter \a ok is for.
+
+    On failed execution, returns always an empty list and deletes possibly 
+    semi-created object hierarchy.
+
     \param fileName file to be processed.
     \param section space separated route to section, that you want to load.
     \param ok indicates if loading was successful.