Commit faac7810 authored by leberre's avatar leberre
Browse files

corrected javadoc 8 errors in core module

git-svn-id: svn+ssh://svn.forge.ow2.org/svnroot/sat4j/maven/trunk@2561 ba638df5-4473-46d1-82f8-c3ae2a17a6e1
parent 9a5e7ea8
......@@ -305,6 +305,7 @@ public abstract class AbstractLauncher implements Serializable, ILogAble {
* Display messages as comments on STDOUT
*
* @param message
* a textual information
*/
public void log(String message) {
if (this.silent)
......@@ -326,6 +327,7 @@ public abstract class AbstractLauncher implements Serializable, ILogAble {
* if solution is very large.
*
* @param value
* true to display the message
*/
protected void setDisplaySolutionLine(boolean value) {
this.displaySolutionLine = value;
......@@ -373,6 +375,7 @@ public abstract class AbstractLauncher implements Serializable, ILogAble {
* default, the solver displays everything on System.out.
*
* @param out
* a new output for the statistics.
*/
public void setLogWriter(PrintWriter out) {
this.out = out;
......
......@@ -82,13 +82,14 @@ public interface ILauncherMode extends SolutionFoundListener {
*
* @param problem
* the problem to solve
* @param reader
* the reader that provided the problem object
* @param logger
* the element that is able to log the result
* @param out
* the printwriter to associate to the solver
* @param beginTime
* the time at which the solver starts
* @return
*/
void solve(IProblem problem, Reader reader, ILogAble logger,
PrintWriter out, long beginTime);
......@@ -98,6 +99,8 @@ public interface ILauncherMode extends SolutionFoundListener {
* solution in case of a time out (for maxsat competitions for instance).
*
* @param isIncomplete
* true if the solver should return the best solution found so
* far.
*/
void setIncomplete(boolean isIncomplete);
......@@ -105,13 +108,16 @@ public interface ILauncherMode extends SolutionFoundListener {
* Allow the launcher to get the current status of the problem: SAT, UNSAT,
* UPPER_BOUND, etc.
*
* @return
* @return the status of the problem.
*/
ExitCode getCurrentExitCode();
/**
* Allow to set a specific exit code to the launcher (in case of trivial
* unsatisfiability for instance).
*
* @param exitCode
* the status of the problem to solve
*/
void setExitCode(ExitCode exitCode);
......
......@@ -35,7 +35,7 @@ import java.util.Iterator;
import org.sat4j.specs.IVec;
/**
* Utility class to allow Read Only access to an IVec<T>.
* Utility class to allow Read Only access to an {@link IVec}.
*
* @author daniel
*
......@@ -45,8 +45,8 @@ import org.sat4j.specs.IVec;
public final class ReadOnlyVec<T> implements IVec<T> {
/**
*
*/
*
*/
private static final long serialVersionUID = 1L;
private final IVec<T> vec;
......
......@@ -280,10 +280,12 @@ public final class Vec<T> implements IVec<T> {
}
/**
* Ces operations devraient se faire en temps constant. Ce n'est pas le cas
* ici.
* Copy the content of the vector to another vector.
*
* THIS METHOD IS NOT SPECIALLY EFFICIENT. USE WITH CAUTION.
*
* @param copy
* a non null vector
*/
public void copyTo(IVec<T> copy) {
final Vec<T> ncopy = (Vec<T>) copy;
......@@ -295,7 +297,14 @@ public final class Vec<T> implements IVec<T> {
}
/**
* Copy the content of the vector to an array.
*
* THIS METHOD IS NOT SPECIALLY EFFICIENT. USE WITH CAUTION.
*
* @param dest
* a non null array, containing sufficient space to copy the
* content of the current vector, i.e.
* <code>dest.length &gt;= this.size()</code>.
*/
public <E> void copyTo(E[] dest) {
// assert dest.length >= nbelem;
......@@ -394,7 +403,10 @@ public final class Vec<T> implements IVec<T> {
}
/**
* Sort the vector according to a given order on the elements.
*
* @param comparator
* a way to order the elements of the vector
*/
public void sort(Comparator<T> comparator) {
sort(0, this.nbelem, comparator);
......
......@@ -121,6 +121,7 @@ public final class VecInt implements IVecInt {
* Remove the latest nofelems elements from the vector
*
* @param nofelems
* the number of elements to remove
*/
public void shrink(int nofelems) {
// assert nofelems >= 0;
......@@ -231,10 +232,11 @@ public final class VecInt implements IVecInt {
}
/**
* Copy the content of this vector into another one. Non constant time
* operation.
* Copy the content of this vector into another one. Uses Java
* {@link System#arraycopy(Object, int, Object, int, int)} to make the copy.
*
* @param copy
* another VecInt vector
*/
public void copyTo(IVecInt copy) {
VecInt ncopy = (VecInt) copy;
......@@ -246,10 +248,11 @@ public final class VecInt implements IVecInt {
}
/**
* Copy the content of this vector into an array of integer. Non constant
* time operation.
* Copy the content of this vector into an array of integer. Uses Java
* {@link System#arraycopy(Object, int, Object, int, int)} to make the copy.
*
* @param is
* the target array.
*/
public void copyTo(int[] is) {
// assert is.length >= nbelem;
......@@ -635,7 +638,10 @@ public final class VecInt implements IVecInt {
}
/**
* Sort the vector according to a given order.
*
* @param comparator
* a way to order the integers of that vector.
*/
public void sort(Comparator<Integer> comparator) {
sort(0, this.nbelem, comparator);
......
......@@ -47,57 +47,62 @@ import org.sat4j.specs.Propagatable;
import org.sat4j.specs.UnitPropagationListener;
import org.sat4j.specs.VarMapper;
public final class MaxWatchCard implements Propagatable, Constr, Undoable,
Serializable {
public final class MaxWatchCard
implements Propagatable, Constr, Undoable, Serializable {
private static final long serialVersionUID = 1L;
/**
* Degr? de la contrainte de cardinalit?
* Degree (right hand side) of the constraint.
*/
private int degree;
/**
* Liste des litt?raux de la contrainte
* Literals (left hand side) of the constraint.
*/
private final int[] lits;
/**
* D?termine si c'est une in?galit? sup?rieure ou ?gale
* Flag to denote greater than or lesser than constraint.
*/
private boolean moreThan;
/**
* Somme des coefficients des litt?raux observ?s
* Sum of the currently watched literals.
*/
private int watchCumul;
/**
* Vocabulaire de la contrainte
* Vocabulary of the constraints.
*/
private final ILits voc;
/**
* Constructeur de base cr?ant des contraintes vides
* Build a new constraint.
*
* @param size
* nombre de litt?raux de la contrainte
* @param learnt
* indique si la contrainte est apprise
* @param voc
* the vocabulary of the constraint.
* @param ps
* a set of literals
* @param moreThan
* true if the constraint is of the form "greater than", else
* false.
* @param degree
* the degree/threshold of the constraint
*/
public MaxWatchCard(ILits voc, IVecInt ps, boolean moreThan, int degree) {
// On met en place les valeurs
// update fields
this.voc = voc;
this.degree = degree;
this.moreThan = moreThan;
// On simplifie ps
// Simply ps
int[] index = new int[voc.nVars() * 2 + 2];
for (int i = 0; i < index.length; i++) {
index[i] = 0;
}
// On repertorie les litt?raux utiles
// Look for opposite literals
for (int i = 0; i < ps.size(); i++) {
if (index[ps.get(i) ^ 1] == 0) {
index[ps.get(i)]++;
......@@ -105,7 +110,7 @@ public final class MaxWatchCard implements Propagatable, Constr, Undoable,
index[ps.get(i) ^ 1]--;
}
}
// On supprime les litt?raux inutiles
// Update degree according to removed literals
int ind = 0;
while (ind < ps.size()) {
if (index[ps.get(ind)] > 0) {
......@@ -120,19 +125,18 @@ public final class MaxWatchCard implements Propagatable, Constr, Undoable,
}
}
// On copie les litt?raux de la contrainte
// Copy literals to the current constraint
this.lits = new int[ps.size()];
ps.moveTo(this.lits);
// On normalise la contrainte au sens de Barth
// Normalize the constraint
normalize();
// Mise en place de l'observation maximale
// Watch all non falsified literals
this.watchCumul = 0;
// On observe les litt?raux non falsifi?
for (int i = 0; i < this.lits.length; i++) {
// Rappel: les ?l?ments falsifi?s ne seront jamais d?pil?s
// Note: those falsified literals will never be unset
if (!voc.isFalsified(this.lits[i])) {
this.watchCumul++;
voc.watch(this.lits[i] ^ 1, this);
......@@ -515,7 +519,8 @@ public final class MaxWatchCard implements Propagatable, Constr, Undoable,
for (int i = 1; i < this.lits.length; i++) {
if (this.voc.isUnassigned(this.lits[i])) {
stb.append(" + "); //$NON-NLS-1$
stb.append(mapper.map(LiteralsUtils.toDimacs(this.lits[i])));
stb.append(
mapper.map(LiteralsUtils.toDimacs(this.lits[i])));
stb.append(" "); //$NON-NLS-1$
}
}
......
......@@ -46,8 +46,8 @@ import org.sat4j.specs.Propagatable;
import org.sat4j.specs.UnitPropagationListener;
import org.sat4j.specs.VarMapper;
public class MinWatchCard implements Propagatable, Constr, Undoable,
Serializable {
public class MinWatchCard
implements Propagatable, Constr, Undoable, Serializable {
private static final long serialVersionUID = 1L;
......@@ -144,10 +144,10 @@ public class MinWatchCard implements Propagatable, Constr, Undoable,
/**
* Constructs and normalizes a cardinality constraint. used by
* MinWatchCardPB.normalizedMinWatchCardNew() in the normalized case. <br />
* MinWatchCardPB.normalizedMinWatchCardNew() in the normalized case.
*
* <strong>Should not be used if parameters are not already
* normalized</strong><br />
* This constraint is always an ATLEAST constraint.
* normalized</strong> This constraint is always an ATLEAST constraint.
*
* @param voc
* vocabulary used by the constraint
......
......@@ -37,7 +37,9 @@ import org.sat4j.specs.Constr;
interface ConstrActivityListener {
/**
* @param outclause
*
* @param confl
* the conflictual constraint
*/
void claBumpActivity(Constr confl);
}
......@@ -61,7 +61,7 @@ public interface DataStructureFactory {
void learnConstraint(Constr constr);
/**
* Create a cardinality constraint of the form sum li >= degree.
* Create a cardinality constraint of the form sum li &gt;= degree.
*
* @param literals
* a set of literals.
......@@ -73,7 +73,8 @@ public interface DataStructureFactory {
Constr createCardinalityConstraint(IVecInt literals, int degree)
throws ContradictionException;
Constr createUnregisteredCardinalityConstraint(IVecInt literals, int degree);
Constr createUnregisteredCardinalityConstraint(IVecInt literals,
int degree);
void setUnitPropagationListener(UnitPropagationListener s);
......
......@@ -43,9 +43,9 @@ import org.sat4j.specs.Propagatable;
* from 2 to 2*n+1.
*
* For a Dimacs variable v, the variable index in SAT4J is v, it's positive
* literal is 2*v (v << 1) and it's negative literal is 2*v+1 ((v<<1)^1). Note
* that one can easily access to the complementary literal of p by using bitwise
* operation ^.
* literal is <code>2*v (v &lt;&lt; 1)</code> and it's negative literal is
* <code>2*v+1 ((v&lt;&lt;1)^1)</code>. Note that one can easily access to the
* complementary literal of p by using bitwise operation ^.
*
* In SAT4J, literals are usualy denoted by p or q and variables by v or x.
*
......
......@@ -409,7 +409,7 @@ public class Solver<D extends DataStructureFactory>
}
public int newVar(int howmany) {
if (this.declaredMaxVarId>0 && howmany > this.declaredMaxVarId
if (this.declaredMaxVarId > 0 && howmany > this.declaredMaxVarId
&& this.voc.nVars() > this.declaredMaxVarId) {
throw new IllegalStateException(
"Caution, you are making solver's internal var id public with uncontrolled consequences with features requiring internal/hidden variables.");
......@@ -495,7 +495,7 @@ public class Solver<D extends DataStructureFactory>
IVecInt vlits = dimacs2internal(literals);
return addConstr(Xor.createParityConstraint(vlits, even, voc));
}
@SuppressWarnings("unchecked")
public boolean simplifyDB() {
// Simplifie la base de clauses apres la premiere propagation des
......@@ -1493,9 +1493,6 @@ public class Solver<D extends DataStructureFactory>
this.learnedConstraintsDeletionStrategy.reduce(this.learnts);
}
/**
* @param learnts
*/
protected void sortOnActivity() {
this.learnts.sort(this.comparator);
}
......
......@@ -43,7 +43,8 @@ public interface VarActivityListener extends Serializable {
* Update the activity of a variable v.
*
* @param p
* a literal (v<<1 or v<<1^1)
* a literal (<code>v&lt;&lt;1</code> or
* <code>v&lt;&lt;1^1</code>)
*/
void varBumpActivity(int p);
}
......@@ -38,13 +38,11 @@ import org.sat4j.specs.Constr;
*
* @author daniel
*
* @param <L>
* a data structure for the literals.
* @param <D>
* a data structure for the clauses.
*/
public final class ClauseOnlyLearning<D extends DataStructureFactory> extends
LimitedLearning<D> {
public final class ClauseOnlyLearning<D extends DataStructureFactory>
extends LimitedLearning<D> {
/**
*
......
......@@ -38,7 +38,7 @@ public interface VariableComparator {
* a variable id
* @param b
* a variable id
* @return true iff a < b (a is preferred to b)
* @return true iff a &lt; b (a is preferred to b)
*/
boolean preferredTo(int a, int b);
}
......@@ -94,8 +94,6 @@ public class DimacsReader extends Reader implements Serializable {
/**
* Skip comments at the beginning of the input stream.
*
* @param in
* the input stream
* @throws IOException
* if an IO problem occurs.
* @since 2.1
......@@ -105,8 +103,6 @@ public class DimacsReader extends Reader implements Serializable {
}
/**
* @param in
* the input stream
* @throws IOException
* iff an IO occurs
* @throws ParseFormatException
......@@ -145,8 +141,6 @@ public class DimacsReader extends Reader implements Serializable {
protected IVecInt literals = new VecInt();
/**
* @param in
* the input stream
* @throws IOException
* iff an IO problems occurs
* @throws ParseFormatException
......@@ -155,8 +149,8 @@ public class DimacsReader extends Reader implements Serializable {
* si le probl?me est trivialement inconsistant.
* @since 2.1
*/
protected void readConstrs() throws IOException, ParseFormatException,
ContradictionException {
protected void readConstrs()
throws IOException, ParseFormatException, ContradictionException {
int realNbOfConstr = 0;
this.literals.clear();
......@@ -181,8 +175,8 @@ public class DimacsReader extends Reader implements Serializable {
if (this.scanner.currentChar() == '%'
&& this.expectedNbOfConstr == realNbOfConstr) {
if (this.solver.isVerbose()) {
System.out
.println("Ignoring the rest of the file (SATLIB format");
System.out.println(
"Ignoring the rest of the file (SATLIB format");
}
break;
}
......@@ -193,9 +187,9 @@ public class DimacsReader extends Reader implements Serializable {
}
}
if (this.checkConstrNb && this.expectedNbOfConstr != realNbOfConstr) {
throw new ParseFormatException("wrong nbclauses parameter. Found "
+ realNbOfConstr + ", " + this.expectedNbOfConstr
+ " expected");
throw new ParseFormatException(
"wrong nbclauses parameter. Found " + realNbOfConstr + ", "
+ this.expectedNbOfConstr + " expected");
}
}
......@@ -217,8 +211,8 @@ public class DimacsReader extends Reader implements Serializable {
/**
* @since 2.1
*/
protected boolean handleLine() throws ContradictionException, IOException,
ParseFormatException {
protected boolean handleLine()
throws ContradictionException, IOException, ParseFormatException {
int lit;
boolean added = false;
while (!this.scanner.eof()) {
......@@ -237,8 +231,8 @@ public class DimacsReader extends Reader implements Serializable {
}
@Override
public IProblem parseInstance(InputStream in) throws ParseFormatException,
ContradictionException, IOException {
public IProblem parseInstance(InputStream in)
throws ParseFormatException, ContradictionException, IOException {
this.scanner = new EfficientScanner(in);
return parseInstance();
}
......@@ -251,8 +245,8 @@ public class DimacsReader extends Reader implements Serializable {
* @throws ContradictionException
* si le probl?me est trivialement inconsitant
*/
private IProblem parseInstance() throws ParseFormatException,
ContradictionException {
private IProblem parseInstance()
throws ParseFormatException, ContradictionException {
this.solver.reset();
try {
skipComments();
......
......@@ -37,8 +37,8 @@ import org.sat4j.specs.IGroupSolver;
public class GroupedCNFReader extends DimacsReader {
/**
*
*/
*
*/
private static final long serialVersionUID = 1L;
private int numberOfComponents;
......@@ -53,8 +53,6 @@ public class GroupedCNFReader extends DimacsReader {
}
/**
* @param in
* the input stream
* @throws IOException
* iff an IO occurs
* @throws ParseFormatException
......@@ -70,8 +68,8 @@ public class GroupedCNFReader extends DimacsReader {
String[] tokens = line.split("\\s+");
if (tokens.length < 5 || !"p".equals(tokens[0])
|| !this.formatString.equals(tokens[1])) {
throw new ParseFormatException("problem line expected (p "
+ this.formatString + " ...)");
throw new ParseFormatException(
"problem line expected (p " + this.formatString + " ...)");
}
int vars;
......@@ -91,8 +89,8 @@ public class GroupedCNFReader extends DimacsReader {
* @since 2.1
*/
@Override
protected boolean handleLine() throws ContradictionException, IOException,
ParseFormatException {
protected boolean handleLine()
throws ContradictionException, IOException, ParseFormatException {
int lit;
boolean added = false;
String component = this.scanner.next();
......@@ -100,12 +98,12 @@ public class GroupedCNFReader extends DimacsReader {
throw new ParseFormatException(
"Component index required at the beginning of the clause");
}
this.currentComponentIndex = Integer.valueOf(component.substring(1,
component.length() - 1));
this.currentComponentIndex = Integer
.valueOf(component.substring(1, component.length() - 1));
if (this.currentComponentIndex < 0
|| this.currentComponentIndex > this.numberOfComponents) {
throw new ParseFormatException("wrong component index: "
+ this.currentComponentIndex);
throw new ParseFormatException(
"wrong component index: " + this.currentComponentIndex);
}
while (!this.scanner.eof()) {
lit = this.scanner.nextInt();
......
......@@ -50,9 +50,9 @@ import org.sat4j.specs.IVecInt;
* Clauses are represented as an array of Dimacs literals (non zero integers).
* Cardinality constraints are represented like a clause for its left hand side,
* a comparator (a string) and a number.
* <code>[[-1,-2,-3],[[1,-2,3],'>',2],[4,-3,6]]</code> for instance represents
* three constraints, two clauses and the cardinality constraint x1 + not x2 +
* x3 > 2.