1.1 --- a/librazor/razor.h	Tue Jul 01 09:22:25 2008 +0100
     1.2 +++ b/librazor/razor.h	Wed Jul 02 14:37:38 2008 -0400
     1.3 @@ -247,8 +247,38 @@
     1.4   * @title: Importer
     1.5   * @short_description: A mechanism for building #razor_set objects
     1.6   *
     1.7 - * For building a razor set from external sources, like yum, rpmdb or
     1.8 - * RPM files.
     1.9 + * The %razor_importer is a helper object for building a razor set
    1.10 + * from external sources, like yum metadata, the RPM database or RPM
    1.11 + * files.
    1.12 + *
    1.13 + * The importer is a stateful object; it has the notion of a current
    1.14 + * package, and the caller can provide meta data such as properties,
    1.15 + * files and similiar for the package as it becomes available.  Once a
    1.16 + * package is fully described, the next pacakge can begin.  When all
    1.17 + * packages have been described to the importer, the importer will
    1.18 + * create a new %razor_set with the specified packages.
    1.19 + *
    1.20 + * A typical use
    1.21 + * of the importer will follow this template:
    1.22 + * |[
    1.23 + * importer = razor_importer_create();
    1.24 + *
    1.25 + * while ( /<!-- -->* more packages to import *<!-- -->/; ) {
    1.26 + *   /<!-- -->* get name, version and arch of next package *<!-- -->/
    1.27 + *   razor_importer_begin_package(importer, name, version, arch);
    1.28 + *   razor_importer_add_details(importer, summary, description, url, license);
    1.29 + *
    1.30 + *   while ( /<!-- -->* more properties to add *<!-- -->/ )
    1.31 + *     razor_importer_add_property(importer, name, flags, version);
    1.32 + *
    1.33 + *   while ( /<!-- -->* [more files to add *<!-- -->/ )
    1.34 + *     razor_importer_add_file(importer, name);
    1.35 + *
    1.36 + *   razor_importer_finish_package(importer);
    1.37 + * }
    1.38 + *
    1.39 + * return razor_importer_finish(importer);
    1.40 + * ]|
    1.41   **/
    1.42  struct razor_importer;
    1.43