ref: refs/heads/master commit 6a439037d5a3fc1f8cffbc95260b8ccad75eb7d9 Author: Klaus Kämpf <kkaempf@suse.de> Date: Wed Mar 11 11:40:27 2009 +0100 improve documentation --- bindings/satsolver.i | 34 +++++++++++++++++++++--- bindings/transaction.i | 65 ++++++++++++++++++++++++++++++++++++----------- 2 files changed, 79 insertions(+), 20 deletions(-) diff --git a/bindings/satsolver.i b/bindings/satsolver.i index 57ef33e..976ed0a 100644 --- a/bindings/satsolver.i +++ b/bindings/satsolver.i @@ -1,14 +1,38 @@ %{ /* -Document-module: Satsolver + =About Satsolver Satsolver is the module namespace for sat-solver bindings. - sat-solver is a dependency solver for rpm-style dependencies - based on a Satisfyability engine. - - See http://en.opensuse.org/Package_Management/Sat_Solver for more + sat-solver provides a repository data cache and a dependency solver + for rpm-style dependencies based on a Satisfyability engine. + + See http://en.opensuse.org/Package_Management/Sat_Solver for details + about the internals of sat-solver. + + ==Working with sat-solver bindings + + The sat-solver bindings provide two main functionalities + * An efficient cache of repository data + * An ultra-fast dependency solver working on the cached data + + The core of the repository cache is represented by the _Pool_. It + represents the context the solver works in. The Pool holds + _Solvables_, representing (RPM-based) packages. Solvables have a + name, a version and an architecture. Solvables usually have + _Dependencies_, organized as sets of _Relation_s Solvables can also + hold additional attribute data, typically everything from the RPM + header, i.e. _vendor_, _download size_, _install size_, etc. + + Solvables within the Pool are grouped in Repositories. Filling the + Pool by loading a .+solv+ file, representing a _Repository_, is the + preferred way. + + In a nutshell: + Pool _has lots of_ Repositories _have lots of_ Solvables _have lots + of_ Attributes. + */ %} diff --git a/bindings/transaction.i b/bindings/transaction.i index abb4a40..6313eb0 100644 --- a/bindings/transaction.i +++ b/bindings/transaction.i @@ -37,43 +37,68 @@ typedef struct _Transaction {} Transaction; { transaction_free( $self ); } /* - * Install (specific) solvable + * Install request + * + * Ensure installation of a solvable by either + * * specifying it directly + * * specify it by name + * * specify a required relation + * + * Except when specified directly, the solver is free to choose any + * solvable matching the request (by name, by relation) + * + * call-seq: + * transaction.install(solvable) -> void + * transaction.install("kernel") -> void + * transaction.install(relation) -> void + * */ void install( XSolvable *xs ) - { return transaction_install_xsolvable( $self, xs ); } + { transaction_install_xsolvable( $self, xs ); } /* - * Remove (specific) solvable + * Remove request + * + * Ensure removal of a solvable by either + * * specifying it directly + * * specify it by name + * * specify a required relation + * + * Except when specified directly, the solver is free to choose any + * solvable matching the request (by name, by relation) + * + * call-seq: + * transaction.remove(solvable) -> void + * transaction.remove("kernel") -> void + * transaction.remove(relation) -> void + * */ void remove( XSolvable *xs ) - { return transaction_remove_xsolvable( $self, xs ); } + { transaction_remove_xsolvable( $self, xs ); } /* * Install solvable by name - * The solver is free to choose any solvable with the given name. */ void install( const char *name ) - { return transaction_install_name( $self, name ); } + { transaction_install_name( $self, name ); } /* * Remove solvable by name - * The solver is free to choose any solvable with the given name. + * */ void remove( const char *name ) - { return transaction_remove_name( $self, name ); } + { transaction_remove_name( $self, name ); } /* * Install solvable by relation - * The solver is free to choose any solvable providing the given - * relation. + * */ void install( const Relation *rel ) - { return transaction_install_relation( $self, rel ); } + { transaction_install_relation( $self, rel ); } /* * Remove solvable by relation - * The solver is free to choose any solvable providing the given - * relation. + * */ void remove( const Relation *rel ) { return transaction_remove_relation( $self, rel ); } @@ -84,8 +109,8 @@ typedef struct _Transaction {} Transaction; "$result = $1 ? Qtrue : Qfalse;"; #endif /* - * Document-method: empty? * Check if the transaction has any jobs attached. + * * call-seq: * transaction.empty? -> bool * @@ -95,6 +120,7 @@ typedef struct _Transaction {} Transaction; /* * Return number of jobs of this transaction + * */ int size() { return transaction_size( $self ); } @@ -103,8 +129,8 @@ typedef struct _Transaction {} Transaction; %rename("clear!") clear(); #endif /* - * Document-method: clear! * Remove all jobs of this transaction + * * call-seq: * transaction.clear! -> void * @@ -117,16 +143,25 @@ typedef struct _Transaction {} Transaction; #endif /* * Get job by index + * * The index is just a convenience access method and * does NOT imply any preference/ordering of the Jobs. * * A Transaction is always considered a set of Jobs. + * + * call-seq: + * transaction.get(42) -> Job + * */ Job *get( unsigned int i ) { return transaction_job_get( $self, i ); } /* * Iterate over each Job of the Transaction. + * + * call-seq: + * transaction.each { |job| ... } + * */ void each() { transaction_jobs_iterate( $self, transaction_jobs_iterate_callback ); } -- To unsubscribe, e-mail: zypp-commit+unsubscribe@opensuse.org For additional commands, e-mail: zypp-commit+help@opensuse.org