ref: refs/heads/master
commit 6a439037d5a3fc1f8cffbc95260b8ccad75eb7d9
Author: Klaus Kämpf
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