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