--- 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.