ref: refs/heads/master
commit aa03908c77f27d51e5ec8ad8ca1abfbfae721c6a
Author: Klaus Kämpf
Date: Fri Mar 6 14:22:15 2009 +0100
Document classes and methods in rdoc-style
---
bindings/pool.i | 250 +++++++++++++++++++++++++++++++++++++++++++-----
bindings/repodata.i | 18 +++-
bindings/rule.i | 5 +-
bindings/satsolver.i | 28 +++---
bindings/transaction.i | 8 ++
5 files changed, 266 insertions(+), 43 deletions(-)
diff --git a/bindings/pool.i b/bindings/pool.i
index 35cbd0d..9359def 100644
--- a/bindings/pool.i
+++ b/bindings/pool.i
@@ -1,5 +1,17 @@
/*-------------------------------------------------------------*/
-/* Pool */
+/* Pool
+
+=begin rdoc
+The pool contains information about solvables
+stored optimized for memory consumption and fast retrieval.
+
+Solvables represent (RPM) packages and are grouped in repositories.
+
+Solving of dependencies works on the pool, usually with a
+distinguished repository of installed solvables.
+=end
+
+*/
%{
/*
@@ -52,14 +64,6 @@ poolnscallback(Pool *pool, void *data, Id name, Id value)
}
-/*
- * Document-class: Satsolverx::Pool
- *
- * The <code>Pool</code> is main data structure. Everything is reachable via the pool.
- * To solve dependencies of <code>Solvable</code>s, you organize them in <code>Repo</code>s
- * (repositories). The pool knows about all repositories and can
- * create a <code>Solver</code> for solving <code>Transaction</code>s
- */
%}
%nodefault _Pool;
@@ -73,7 +77,14 @@ typedef struct _Pool {} Pool;
%extend Pool {
/*
- * Pool creation
+ * Document-method: new
+ * Pool creation, optionally with an architecture
+ * If you don't pass the architecture to the Pool constructor, you
+ * can also use pool.arch= later.
+ * call-seq:
+ * Pool.new -> Pool
+ * Pool.new("x86_64") -> Pool
+ *
*/
Pool( const char *arch = NULL )
{
@@ -88,7 +99,7 @@ typedef struct _Pool {} Pool;
}
/*
- * discard
+ * Document-method: discard
*
* There is no destructor defined for Pool since the pool pointer
* is mostly used implicitly (e.g. in Solvable or Solver) which
@@ -102,26 +113,49 @@ typedef struct _Pool {} Pool;
void discard()
{ pool_free($self); }
+ /*
+ * Document-method: solvable
+ * Access Solvable storage within the pool
+ * Get solvable based on id from pool
+ *
+ * call-seq:
+ * pool.solvable(id) -> Solvable
+ *
+ */
XSolvable *solvable(int id)
{
return xsolvable_new( $self, (Id)id);
}
+
+ /*
+ * Document-method: relation
+ * Access Solvable storage within the pool
+ * Get relation based on id from Pool
+ *
+ * call-seq:
+ * pool.relation(id) -> Relation
+ *
+ */
Relation *relation( int rel )
{ return relation_new( $self, (Id)rel ); }
#if defined(SWIGRUBY)
%{
-/*
- Document-method: Satsolver::Pool.set_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
- systems, 64bit systems most probably need "x86_64"
-
- call-seq:
- pool.arch = "i686"
-*/
+ /*
+ * 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
+ * systems, 64bit systems most probably need "x86_64"
+ * Attn: There is no getter function for the architecture since
+ * setting an architecture is converted to a list of 'compatible'
+ * 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"
+ *
+ */
%}
%rename( "arch=" ) set_arch( const char *arch );
#endif
@@ -129,27 +163,55 @@ typedef struct _Pool {} Pool;
{ pool_setarch( $self, arch ); }
#if defined(SWIGRUBY)
+ /*
+ * Document-method: debug=
+ * Increase verbosity on stderr
+ *
+ * call-seq:
+ * pool.debug = 1
+ *
+ */
%rename( "debug=" ) set_debug( int level );
#endif
%feature("autodoc", "Makes the stuff noisy on stderr.") set_debug;
void set_debug( int level )
{ pool_setdebuglevel( $self, level ); }
+ /*
+ * Document-method: promoteepoch
+ * If epoch should be promoted
+ *
+ */
int promoteepoch()
{ return $self->promoteepoch; }
#if defined(SWIGRUBY)
- %rename( "promoteepoch=" ) set_promoteepoch( int level );
+ /*
+ * Document-method: promoteepoch=
+ * If epoch should be promoted
+ *
+ */
+ %rename( "promoteepoch=" ) set_promoteepoch( int b );
#endif
void set_promoteepoch( int b )
{ $self->promoteepoch = b; }
+ /*
+ * Document-method:
+ *
+ */
int unprepared()
{ return $self->whatprovides == NULL; }
+ /*
+ * Document-method:
+ *
+ */
void prepare()
{ pool_createwhatprovides( $self ); }
/*
+ * Document-method:
+ *
* System solvable
*/
XSolvable* system()
@@ -161,6 +223,10 @@ typedef struct _Pool {} Pool;
* Repo management
*/
+ /*
+ * Document-method:
+ *
+ */
Repo *add_file( FILE *fp )
{
Repo *repo = repo_create( $self, NULL );
@@ -169,6 +235,10 @@ typedef struct _Pool {} Pool;
}
#if defined(SWIGRUBY)
+ /*
+ * Document-method:
+ *
+ */
Repo *add_solv( VALUE name )
{
const char *fname;
@@ -188,6 +258,10 @@ typedef struct _Pool {} Pool;
return repo;
}
+ /*
+ * Document-method:
+ *
+ */
Repo *add_rpmdb( const char *rootdir )
{
Repo *repo = repo_create( $self, NULL );
@@ -195,12 +269,24 @@ typedef struct _Pool {} Pool;
return repo;
}
+ /*
+ * Document-method:
+ *
+ */
Repo *create_repo( const char *name )
{ return repo_create( $self, name ); }
+ /*
+ * Document-method:
+ *
+ */
int count_repos()
{ return $self->nrepos; }
+ /*
+ * Document-method:
+ *
+ */
Repo *get_repo( int i )
{
if ( i < 0 ) return NULL;
@@ -209,6 +295,10 @@ typedef struct _Pool {} Pool;
}
#if defined(SWIGRUBY)
+ /*
+ * Document-method:
+ *
+ */
void each_repo()
{
int i;
@@ -225,6 +315,10 @@ typedef struct _Pool {} Pool;
%}
#endif
+ /*
+ * Document-method:
+ *
+ */
Repo *find_repo( const char *name )
{
int i;
@@ -239,6 +333,10 @@ typedef struct _Pool {} Pool;
* Relation management
*/
+ /*
+ * Document-method:
+ *
+ */
Relation *create_relation( const char *name, int op = 0, const char *evr = NULL )
{
if (op && !evr)
@@ -261,7 +359,11 @@ typedef struct _Pool {} Pool;
#if defined(SWIGRUBY)
/*
- * iterate over providers of relation
+ * Document-method: each_provider(Relation)
+ * iterate over all providers of a relation
+ * call-seq:
+ * pool.each_provider(relation) { |solvable| ... }
+ *
*/
void each_provider( Relation *rel )
{
@@ -275,6 +377,14 @@ typedef struct _Pool {} Pool;
}
}
+ /*
+ * Document-method: each_provider(string)
+ * iterate over all providers of a string
+ * call-seq:
+ * pool.each_provider("glibc") { |solvable| ... }
+ * pool.each_provider("/usr/bin/bash") { |solvable| ... }
+ *
+ */
void each_provider( const char *name )
{
Id p, pp;
@@ -287,6 +397,12 @@ typedef struct _Pool {} Pool;
}
}
+ /*
+ * Document-method: each_provider(id)
+ * iterater over all providers of a specific id
+ * INTERNAL
+ *
+ */
void each_provider( int id )
{
if (id > 0 && id < $self->whatprovidesdataoff) {
@@ -319,6 +435,10 @@ typedef struct _Pool {} Pool;
%}
#endif
+ /*
+ * Document-method:
+ *
+ */
int providers_count( const char *name )
{ int i = 0;
Id v, *vp;
@@ -327,6 +447,10 @@ typedef struct _Pool {} Pool;
return i;
}
+ /*
+ * Document-method:
+ *
+ */
int providers_count( Relation *rel )
{ int i = 0;
Id v, *vp;
@@ -335,12 +459,20 @@ typedef struct _Pool {} Pool;
return i;
}
+ /*
+ * Document-method:
+ *
+ */
XSolvable *providers_get( const char *name, int i)
{ Id *vp;
vp = pool_whatprovides_ptr($self, str2id( $self, name, 0));
return xsolvable_new( $self, *(vp + i));
}
+ /*
+ * Document-method:
+ *
+ */
XSolvable *providers_get( Relation *rel, int i)
{ Id *vp;
vp = pool_whatprovides_ptr($self, rel->id);
@@ -366,7 +498,11 @@ typedef struct _Pool {} Pool;
* Solvable management
*/
- /* number of solvables in pool
+ /*
+ * Document-method:
+ *
+ *
+ * number of solvables in pool
*/
int size()
{ /* skip Ids 0(reserved) and 1(system) */
@@ -374,6 +510,14 @@ 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
+ *
+ */
%rename( "installable?" ) installable( XSolvable *s );
%typemap(out) int installable
"$result = ($1 != 0) ? Qtrue : Qfalse;";
@@ -381,11 +525,26 @@ typedef struct _Pool {} Pool;
int installable( XSolvable *s )
{ return pool_installable( $self, pool_id2solvable( s->pool, s->id ) ); }
- /* return number of iterations when iterating over solvables */
+ /*
+ * Document-method: count
+ * Return number of solvables in the pool
+ *
+ * call-seq:
+ * pool.count -> int
+ *
+ */
int count()
{ return pool_xsolvables_count( $self ); }
#if defined(SWIGRUBY)
+ /*
+ * Document-method: each
+ * Iterate over all solvables in the pool
+ *
+ * call-seq:
+ * pool.each { |solvable| ... }
+ *
+ */
void each()
{ pool_xsolvables_iterate( $self, generic_xsolvables_iterate_callback, NULL ); }
#endif
@@ -422,6 +581,10 @@ typedef struct _Pool {} Pool;
%}
#endif
+ /*
+ * Document-method:
+ *
+ */
XSolvable *find( char *name, Repo *repo = NULL )
{ return xsolvable_find( $self, name, repo ); }
@@ -438,6 +601,10 @@ typedef struct _Pool {} Pool;
#endif
#if defined(SWIGRUBY)
+ /*
+ * Document-method:
+ *
+ */
void search(const char *match, int flags, XSolvable *xs = NULL, const char *keyname = NULL)
{
Dataiterator *di;
@@ -453,6 +620,10 @@ typedef struct _Pool {} Pool;
* Transaction management
*/
+ /*
+ * Document-method:
+ *
+ */
Transaction *create_transaction()
{ return transaction_new( $self ); }
@@ -461,13 +632,40 @@ typedef struct _Pool {} Pool;
*/
#if defined(SWIGRUBY)
+ /*
+ * Document-method: installed=
+ * Set the repository representing the installed solvables
+ * call-seq:
+ * pool.installed = repository
+ *
+ */
%rename( "installed=" ) set_installed( Repo *repo );
#endif
void set_installed(Repo *installed = NULL)
{
pool_set_installed( $self, installed);
}
+
+ /*
+ * Document-method: installed
+ * Return the repository representing the installed solvables.
+ * Returns nil if installed= was not called before.
+ * call-seq:
+ * pool.installed -> repository
+ *
+ */
+ Repo *installed()
+ {
+ return $self->installed;
+ }
+ /*
+ * Document-method: create_solver
+ * Create a solver for this pool
+ * call-seq:
+ * pool.create_solver -> Solver
+ *
+ */
Solver* create_solver()
{
pool_createwhatprovides( $self );
diff --git a/bindings/repodata.i b/bindings/repodata.i
index 539f40c..fc6cb2b 100644
--- a/bindings/repodata.i
+++ b/bindings/repodata.i
@@ -7,14 +7,23 @@
typedef struct _Repodata {} Repodata;
+/* no constructor, Repodata is embedded in Repo */
%extend Repodata {
- /* no constructor, Repodata is embedded in Repo */
- /* number of keys in this Repodata */
- int keysize()
+ /*
+ * Document-method: size
+ * number of keys in this Repodata
+ */
+ int size()
{ return $self->nkeys-1; } /* key 0 is reserved */
- /* access Repokey by index */
+ /*
+ * Document-method: key
+ * access Repokey by index
+ */
+#if defined(SWIGRUBY)
+ %alias key "[]";
+#endif
XRepokey *key( int i )
{
if (i >= 0 && i < $self->nkeys-1)
@@ -24,6 +33,7 @@ typedef struct _Repodata {} Repodata;
#if defined(SWIGRUBY)
/*
+ * Document-method: each_key
* Iterate over each key
*/
void each_key()
diff --git a/bindings/rule.i b/bindings/rule.i
index 500cc27..e12e507 100644
--- a/bindings/rule.i
+++ b/bindings/rule.i
@@ -1,12 +1,15 @@
/*
* Rule
+=begin rdoc
+This documents rule
+=end
*/
%nodefault rule;
%rename(Rule) rule;
typedef struct rule {} Rule;
-
+
%extend Rule {
/* no constructor, Rule is embedded in Solver */
diff --git a/bindings/satsolver.i b/bindings/satsolver.i
index e630803..a22c67c 100644
--- a/bindings/satsolver.i
+++ b/bindings/satsolver.i
@@ -1,16 +1,20 @@
%{
-/* Document-module: 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.
- *
- *
- * It might make a lot of sense to make Pool* a singular within
- * the module and use this pointer globally instead of carrying
- * it around in every data structure.
- */
+/*
+
+=begin rdoc
+
+ SatSolver is the module namespace for sat-solver bindings.
+
+ sat-solver is a dependency solver for rpm-style dependencies
+ based on a Satisfyability engine.
+
+
+ It might make a lot of sense to make Pool* a singular within
+ the module and use this pointer globally instead of carrying
+ it around in every data structure.
+=end
+
+*/
%}
%module satsolver
diff --git a/bindings/transaction.i b/bindings/transaction.i
index 644fd38..abb4a40 100644
--- a/bindings/transaction.i
+++ b/bindings/transaction.i
@@ -84,7 +84,11 @@ 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
+ *
*/
int empty()
{ return ( $self->queue.count == 0 ); }
@@ -99,7 +103,11 @@ typedef struct _Transaction {} Transaction;
%rename("clear!") clear();
#endif
/*
+ * Document-method: clear!
* Remove all jobs of this transaction
+ * call-seq:
+ * transaction.clear! -> void
+ *
*/
void clear()
{ queue_empty( &($self->queue) ); }
--
To unsubscribe, e-mail: zypp-commit+unsubscribe@opensuse.org
For additional commands, e-mail: zypp-commit+help@opensuse.org
