Add documentation for solver.get_decision()

And no longer document the obsolete describe_decision method.

diff --git a/doc/gen/libsolv-bindings.3 b/doc/gen/libsolv-bindings.3
index 837927d68407914e1acbb5ef44e58a77db27c5aa..3e1d7fa9e3573637e5ab2b9288702388306ac8bc 100644 (file)
--- a/doc/gen/libsolv-bindings.3
+++ b/doc/gen/libsolv-bindings.3
@@ -2,12 +2,12 @@
 .\"     Title: Libsolv-Bindings
 .\"    Author: [see the "Author" section]
 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.\"      Date: 12/12/2022
+.\"      Date: 12/13/2022
 .\"    Manual: LIBSOLV
 .\"    Source: libsolv
 .\"  Language: English
 .\"
-.TH "LIBSOLV\-BINDINGS" "3" "12/12/2022" "libsolv" "LIBSOLV"
+.TH "LIBSOLV\-BINDINGS" "3" "12/13/2022" "libsolv" "LIBSOLV"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -4339,46 +4339,46 @@ Return the transaction to implement the calculated package changes\&. A transact
 .RS 4
 .\}
 .nf
-\fBint\fR \fIreason\fR \fB= describe_decision(Solvable *\fR\fIs\fR\fB, Rule *\fR\fIOUTPUT\fR\fB)\fR
-my \fB(\fR\fI$reason\fR\fB,\fR \fI$rule\fR\fB) =\fR \fI$solver\fR\fB\->describe_decision(\fR\fI$solvable\fR\fB)\fR;
-\fB(\fR\fIreason\fR\fB,\fR \fIrule\fR\fB) =\fR \fIsolver\fR\fB\&.describe_decision(\fR\fIsolvable\fR\fB)\fR
-\fB(\fR\fIreason\fR\fB,\fR \fIrule\fR\fB) =\fR \fIsolver\fR\fB\&.describe_decision(\fR\fIsolvable\fR\fB)\fR
+\fBSolvable *get_recommended(bool\fR \fInoselected\fR\fB=0)\fR
+my \fI@solvables\fR \fB=\fR \fI$solver\fR\fB\->get_recommended()\fR;
+\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_recommended()\fR
+\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_recommended()\fR
 .fi
 .if n \{\
 .RE
 .\}
 .sp
-Return the reason why a specific solvable was installed or erased\&. For most of the reasons the rule that triggered the decision is also returned\&.
+Return all solvables that are recommended by the solver run result\&. This includes solvables included in the result; set noselected if you want to filter those\&.
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
-\fBSolvable *get_recommended(bool\fR \fInoselected\fR\fB=0)\fR
-my \fI@solvables\fR \fB=\fR \fI$solver\fR\fB\->get_recommended()\fR;
-\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_recommended()\fR
-\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_recommended()\fR
+\fBSolvable *get_suggested(bool\fR \fInoselected\fR\fB=0)\fR
+my \fI@solvables\fR \fB=\fR \fI$solver\fR\fB\->get_suggested()\fR;
+\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_suggested()\fR
+\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_suggested()\fR
 .fi
 .if n \{\
 .RE
 .\}
 .sp
-Return all solvables that are recommended by the solver run result\&. This includes solvables included in the result, set noselected if you want to filter those\&.
+Return all solvables that are suggested by the solver run result\&. This includes solvables included in the result; set noselected if you want to filter those\&.
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
-\fBSolvable *get_suggested(bool\fR \fInoselected\fR\fB=0)\fR
-my \fI@solvables\fR \fB=\fR \fI$solver\fR\fB\->get_suggested()\fR;
-\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_suggested()\fR
-\fIsolvables\fR \fB=\fR \fIsolver\fR\fB\&.get_suggested()\fR
+\fIDecision\fR \fB= get_decision(Solvable *\fR\fIs\fR\fB)\fR
+my \fI$decision\fR \fB=\fR \fI$solver\fR\fB\->get_decision(\fR\fI$solvable\fR\fB)\fR;
+\fIdecision\fR \fB=\fR \fIsolver\fR\fB\&.get_decision(\fR\fIsolvable\fR\fB)\fR;
+\fIdecision\fR \fB=\fR \fIsolver\fR\fB\&.get_decision(\fR\fIsolvable\fR\fB)\fR;
 .fi
 .if n \{\
 .RE
 .\}
 .sp
-Return all solvables that are suggested by the solver run result\&. This includes solvables included in the result, set noselected if you want to filter those\&.
+Return a decision object that describes why a specific solvable was installed or erased\&. See the Decision class for more information\&.
 .sp
 .if n \{\
 .RS 4
@@ -4393,7 +4393,7 @@ my \fI@decisions\fR \fB=\fR \fI$solver\fR\fB\->get_decisionlist(\fR\fI$solvable\
 .RE
 .\}
 .sp
-Return a list of decisions that caused the specific solvable to be installed or erased\&. This is usually more useful than the describe_decision() method, as it returns every involved decision instead of just a single one\&.
+Return a list of decisions that caused the specific solvable to be installed or erased\&. This is usually more useful than the get_decision() method, as it returns every involved decision instead of just a single one\&.
 .sp
 .if n \{\
 .RS 4

diff --git a/doc/libsolv-bindings.txt b/doc/libsolv-bindings.txt
index a72a8aeed08579317b15b158988cf3ad57ed861d..126e143335d79213c7a1d3794b652ad7ae50f7bb 100644 (file)
--- a/doc/libsolv-bindings.txt
+++ b/doc/libsolv-bindings.txt
@@ -2664,21 +2664,13 @@ Return the transaction to implement the calculated package changes. A transactio
 is available even if problems were found, this is useful for interactive user
 interfaces that show both the job result and the problems.
 
-       int reason = describe_decision(Solvable *s, Rule *OUTPUT)
-       my ($reason, $rule) = $solver->describe_decision($solvable);
-       (reason, rule) = solver.describe_decision(solvable)
-       (reason, rule) = solver.describe_decision(solvable)
-
-Return the reason why a specific solvable was installed or erased. For most of
-the reasons the rule that triggered the decision is also returned.
-
        Solvable *get_recommended(bool noselected=0)
        my @solvables = $solver->get_recommended();
        solvables = solver.get_recommended()
        solvables = solver.get_recommended()
 
 Return all solvables that are recommended by the solver run result. This includes
-solvables included in the result, set noselected if you want to filter those.
+solvables included in the result; set noselected if you want to filter those.
 
        Solvable *get_suggested(bool noselected=0)
        my @solvables = $solver->get_suggested();
@@ -2686,7 +2678,15 @@ solvables included in the result, set noselected if you want to filter those.
        solvables = solver.get_suggested()
 
 Return all solvables that are suggested by the solver run result. This includes
-solvables included in the result, set noselected if you want to filter those.
+solvables included in the result; set noselected if you want to filter those.
+
+       Decision = get_decision(Solvable *s)
+       my $decision = $solver->get_decision($solvable);
+       decision = solver.get_decision(solvable);
+       decision = solver.get_decision(solvable);
+
+Return a decision object that describes why a specific solvable was installed or erased.
+See the Decision class for more information.
 
        Decision *get_decisionlist(Solvable *s)
        my @decisions = $solver->get_decisionlist($solvable);
@@ -2694,7 +2694,7 @@ solvables included in the result, set noselected if you want to filter those.
        decisions = solver.get_decisionlist(solvable)
 
 Return a list of decisions that caused the specific solvable to be installed or
-erased. This is usually more useful than the describe_decision() method, as it
+erased. This is usually more useful than the get_decision() method, as it
 returns every involved decision instead of just a single one.
 
        Alternative *alternatives()