ref: refs/heads/master
commit fa1a3efb257c553266039e4e6978f42d1a704c4f
Author: Klaus Kämpf
Date: Mon Mar 9 17:25:35 2009 +0100
Bindings documentation improvements
---
bindings/dependency.i | 24 +++----
bindings/pool.i | 159 ++++++++++++++++++++++++++++++++++++++-----------
bindings/rule.i | 10 ++-
bindings/solvable.i | 6 +-
bindings/solver.i | 35 +++++------
5 files changed, 159 insertions(+), 75 deletions(-)
diff --git a/bindings/dependency.i b/bindings/dependency.i
index b6ff9b4..9b8e980 100644
--- a/bindings/dependency.i
+++ b/bindings/dependency.i
@@ -1,18 +1,14 @@
/*
- * Dependency
-=begin rdoc
-Document-class: Dependency
-A dependency is a set of Relations. There are eight types of
-dependencies:
-* provides
-* requires
-* conflicts
-* obsoletes
-* recommends
-* suggests
-* supplements
-* enhances
-=end
+ * A dependency is a set of Relations. There are eight types of dependencies:
+ * * provides
+ * * requires
+ * * conflicts
+ * * obsoletes
+ * * recommends
+ * * suggests
+ * * supplements
+ * * enhances
+ *
*/
%{
diff --git a/bindings/pool.i b/bindings/pool.i
index 9e6bf3b..11c9c68 100644
--- a/bindings/pool.i
+++ b/bindings/pool.i
@@ -152,6 +152,7 @@ typedef struct _Pool {} Pool;
%{
/*
* Document-method: arch=
+ *
* Defines the architecture of the pool. Only Solvables with a compatible
* architecture will be considered.
* Setting the architecture to "i686" is a good choice for most 32bit
@@ -161,6 +162,7 @@ typedef struct _Pool {} Pool;
* architectures internally. E.g. i686 is actually
* i686,i586,i486,i386,noach. The solver will always choose the
* 'best' architecture from this list.
+ *
* call-seq:
* pool.arch = "i686"
*
@@ -174,6 +176,7 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
* Document-method: debug=
+ *
* Increase verbosity on stderr
*
* call-seq:
@@ -188,6 +191,7 @@ typedef struct _Pool {} Pool;
/*
* Document-method: promoteepoch
+ *
* If epoch should be promoted
*
*/
@@ -196,6 +200,7 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
* Document-method: promoteepoch=
+ *
* If epoch should be promoted
*
*/
@@ -205,23 +210,32 @@ typedef struct _Pool {} Pool;
{ $self->promoteepoch = b; }
/*
- * Document-method:
+ * Set the pool to an _unprepared_ status.
+ * You must run Pool.prepare before using a solver on this Pool.
+ *
+ * See also Pool.prepare
*
*/
int unprepared()
{ return $self->whatprovides == NULL; }
/*
- * Document-method:
+ * Prepare the pool for solving. After calling prepare, one must not
+ * add or remove Repositories or add/remove Solvables within a Repository.
*
*/
void prepare()
{ pool_createwhatprovides( $self ); }
/*
- * Document-method:
+ * Get system solvable
+ *
+ * This is an internal solvable representing requirements of the
+ * system where satsolver is running.
+ *
+ * call-seq:
+ * pool.system -> Solvable
*
- * System solvable
*/
XSolvable* system()
{
@@ -233,7 +247,12 @@ typedef struct _Pool {} Pool;
*/
/*
- * Document-method:
+ * Add opened .+solv+ file to pool.
+ *
+ * Returns newly created Repository
+ *
+ * call-seq:
+ * pool.add_file( File.open( "foo.solv" ) ) -> Repository
*
*/
Repo *add_file( FILE *fp )
@@ -245,7 +264,12 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * Document-method:
+ * Add .+solv+ file to Pool
+ *
+ * Returns newly created Repository
+ *
+ * call-seq:
+ * pool.add_solv( "foo.solv" ) -> Repository
*
*/
Repo *add_solv( VALUE name )
@@ -268,7 +292,16 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method:
+ * Add RPM database to Pool.
+ *
+ * For chrooted RPM databases, pass the toplevel directory as
+ * parameter.
+ *
+ * Returns a newly created Repository
+ *
+ * call-seq:
+ * pool.add_rpmdb -> Repository
+ * pool.add_rpmdb("/space/chroot") -> Repository
*
*/
Repo *add_rpmdb( const char *rootdir )
@@ -279,21 +312,35 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method:
+ * Create an empty repository, optionally with a name.
+ *
+ * This repository should then be populated with Solvables.
+ *
+ * call-seq:
+ * pool.create_repo -> Repository
+ * pool.create_repo("test") -> Repository
*
*/
- Repo *create_repo( const char *name )
+ Repo *create_repo( const char *name = NULL )
{ return repo_create( $self, name ); }
/*
- * Document-method:
+ * Return the number of repositories in this pool
+ *
+ * call-seq:
+ * pool.count_repos -> int
*
*/
int count_repos()
{ return $self->nrepos; }
/*
- * Document-method:
+ * Get a repository by index from the pool.
+ * Returns +nil+ if no such Repository exists.
+ *
+ * call-seq:
+ * pool.get_repo(2) -> Repository
+ * pool.get_repo(-42) -> nil
*
*/
Repo *get_repo( int i )
@@ -305,7 +352,10 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * Document-method:
+ * Interate through all Repositories of this Pool
+ *
+ * call-seq:
+ * pool.each_repo { |repository| ... }
*
*/
void each_repo()
@@ -325,7 +375,11 @@ typedef struct _Pool {} Pool;
#endif
/*
- * Document-method:
+ * Find Repository by name. Returns +nil+ if no Repository with the
+ * given name exists.
+ *
+ * call-seq:
+ * pool.find_repo("test") -> Repository
*
*/
Repo *find_repo( const char *name )
@@ -343,7 +397,13 @@ typedef struct _Pool {} Pool;
*/
/*
- * Document-method:
+ * Create a relation.
+ *
+ * See also: Relation.new()
+ *
+ * call-seq:
+ * pool.create_relation( "kernel" ) -> Relation
+ * pool.create_relation( "kernel", REL_GE, "2.6.26" ) -> Relation
*
*/
Relation *create_relation( const char *name, int op = 0, const char *evr = NULL )
@@ -368,8 +428,8 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * Document-method: each_provider(Relation)
- * iterate over all providers of a relation
+ * Iterate over all providers of a relation
+ *
* call-seq:
* pool.each_provider(relation) { |solvable| ... }
*
@@ -387,8 +447,8 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method: each_provider(string)
- * iterate over all providers of a string
+ * Iterate over all providers of a string
+ *
* call-seq:
* pool.each_provider("glibc") { |solvable| ... }
* pool.each_provider("/usr/bin/bash") { |solvable| ... }
@@ -407,8 +467,8 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method: each_provider(id)
- * iterater over all providers of a specific id
+ * Iterater over all providers of a specific id
+ *
* INTERNAL
*
*/
@@ -445,7 +505,10 @@ typedef struct _Pool {} Pool;
#endif
/*
- * Document-method:
+ * Count number of solvables providing _name_
+ *
+ * call-seq:
+ * pool.providers_count("kernel") { |solvable| ... }
*
*/
int providers_count( const char *name )
@@ -457,7 +520,10 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method:
+ * Count number of solvables providing _relation_
+ *
+ * call-seq:
+ * pool.providers_count(relation) { |solvable| ... }
*
*/
int providers_count( Relation *rel )
@@ -469,7 +535,9 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method:
+ * Return n'th provider providing _name_
+ *
+ * INTERNAL
*
*/
XSolvable *providers_get( const char *name, int i)
@@ -479,7 +547,9 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method:
+ * Return n'th provider providing _relation_
+ *
+ * INTERNAL
*
*/
XSolvable *providers_get( Relation *rel, int i)
@@ -488,11 +558,11 @@ typedef struct _Pool {} Pool;
return xsolvable_new( $self, *(vp + i));
}
+#if defined(SWIGPYTHON)
/*
* providers iterator for Python
* using providers_count and providers_get
*/
-#if defined(SWIGPYTHON)
%pythoncode %{
def providers(self,what):
if self.unprepared():
@@ -508,10 +578,11 @@ typedef struct _Pool {} Pool;
*/
/*
- * Document-method:
+ * Return number of Solvables in pool
*
+ * call-seq:
+ * pool.size -> int
*
- * number of solvables in pool
*/
int size()
{ /* skip Ids 0(reserved) and 1(system) */
@@ -520,9 +591,9 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * Document-method: installable?
* Find out if a solvable is installable (all its dependencies can
* be satisfied)
+ *
* call-seq:
* pool.installable?(Solvable) -> true
*
@@ -535,7 +606,6 @@ typedef struct _Pool {} Pool;
{ return pool_installable( $self, pool_id2solvable( s->pool, s->id ) ); }
/*
- * Document-method: count
* Return number of solvables in the pool
*
* call-seq:
@@ -547,7 +617,6 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * Document-method: each
* Iterate over all solvables in the pool
*
* call-seq:
@@ -591,7 +660,17 @@ typedef struct _Pool {} Pool;
#endif
/*
- * Document-method:
+ * Find solvable by name.
+ *
+ * Optionally restrict search to a Repository.
+ *
+ * This function is useful to detect if a Solvable exists at all. If
+ * multiple Solvables would match, this call returns any one of them. Use
+ * +pool+.+each_provider+ to interate over all matches.
+ *
+ * call-seq:
+ * pool.find("kernel") -> Solvable
+ * pool.find("kernel", this_repo) -> Solvable
*
*/
XSolvable *find( char *name, Repo *repo = NULL )
@@ -611,7 +690,12 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * Document-method:
+ * Search for Solvable attributes
+ *
+ * call-seq:
+ * pool.search("match", flags) { |iterator| ... }
+ * pool.search("match", flags, solvable) { |iterator| ... }
+ * pool.search("match", flags, solvable, key) { |iterator| ... }
*
*/
void search(const char *match, int flags, XSolvable *xs = NULL, const char *keyname = NULL)
@@ -630,7 +714,8 @@ typedef struct _Pool {} Pool;
*/
/*
- * Document-method:
+ * Create an empty Transaction.
+ * See also +Transaction+.+new+
*
*/
Transaction *create_transaction()
@@ -642,8 +727,8 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * Document-method: installed=
* Set the repository representing the installed solvables
+ *
* call-seq:
* pool.installed = repository
*
@@ -656,9 +741,9 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method: installed
* Return the repository representing the installed solvables.
* Returns nil if installed= was not called before.
+ *
* call-seq:
* pool.installed -> repository
*
@@ -669,8 +754,10 @@ typedef struct _Pool {} Pool;
}
/*
- * Document-method: create_solver
* Create a solver for this pool
+ *
+ * See also +Solver+.+new+
+ *
* call-seq:
* pool.create_solver -> Solver
*
diff --git a/bindings/rule.i b/bindings/rule.i
index e12e507..f54c00f 100644
--- a/bindings/rule.i
+++ b/bindings/rule.i
@@ -1,8 +1,12 @@
/*
* Rule
-=begin rdoc
-This documents rule
-=end
+ *
+ * A rule is the internal representation of the _working queue_ of the
+ * solver. Each transaction item and each dependency is converted to a
+ * rule the solver operates on.
+ *
+ * Rules are useful to traceback a decision or a problem.
+ *
*/
%nodefault rule;
diff --git a/bindings/solvable.i b/bindings/solvable.i
index 94e8a99..e1d6246 100644
--- a/bindings/solvable.i
+++ b/bindings/solvable.i
@@ -1,8 +1,6 @@
/*
- * Solvable
-=begin rdoc
-Document-class: Solvable
-=end
+ * Solvable is the representation of a (RPM) package within Satsolver.
+ *
*/
%nodefault _Solvable;
diff --git a/bindings/solver.i b/bindings/solver.i
index a1873da..083f318 100644
--- a/bindings/solver.i
+++ b/bindings/solver.i
@@ -1,23 +1,22 @@
/*
* Solver
-=begin rdoc
-Document-class: Solver
-The solver class is at the heart of the satsolver, providing
-ultra-fast dependency resolution.
-
-The solver is always attached to a pool, containing all solvables the
-solver can operate on. The pool also has designated repository for
-'installed' solvables.
-
-Solving is done by creating Transactions and feeding them to the
-solver as input. On success (solver.solve() returning 'true'), one can
-retrieve the Decisions made by the solver (i.e. install this, remove
-that, update those). On failure, the solver creates a list of
-Problems, explaining what went wrong and how to resolve the problem.
-
-Solving can be controlled globally by setting solver flags.
-Additionally, specific constraints can be set by using Covenants.
-=end
+ *
+ * The solver class is at the heart of the satsolver, providing
+ * ultra-fast dependency resolution.
+ *
+ * The solver is always attached to a pool, containing all solvables the
+ * solver can operate on. The pool also has designated repository for
+ * 'installed' solvables.
+ *
+ * Solving is done by creating Transactions and feeding them to the
+ * solver as input. On success (solver.solve() returning 'true'), one can
+ * retrieve the Decisions made by the solver (i.e. install this, remove
+ * that, update those). On failure, the solver creates a list of
+ * Problems, explaining what went wrong and how to resolve the problem.
+ *
+ * Solving can be controlled globally by setting solver flags.
+ * Additionally, specific constraints can be set by using Covenants.
+ *
*/
%{
--
To unsubscribe, e-mail: zypp-commit+unsubscribe@opensuse.org
For additional commands, e-mail: zypp-commit+help@opensuse.org