Add JavaDoc to "phase"

I am reading https://github.com/logic-ng/LogicNG#first-steps:

final Literal notC = f.literal("C", false);

The documentation states that phase is a Boolean parameter. There is no documentation on the phase in README.md and not at the JavaDoc of literal.

I wonder why

a) phase is not en enum? An enum makes the possibilities clear. Currently with false I don’t know whether there is no phase processing, if its a phase, where all variables are false, an initialization phase, … - Reading the code I would have set it to true, but I am not sure.

b) There is no literal creator without any phase parameter (and then setting a default phase)

Would is be, additionally, possible to describe the phase in the README.md file?

(Issue created in my the context of my free-time project JabRef)

[czengler]

You can always use the not function in LogicNG with a variable - so you never have to construct a literal explicitly 😃 You can write your example with

final FormulaFactory f = new FormulaFactory();
final Formula formula = f.or(f.not(f.variable("a")), f.variable("b"));

Internally the f.not(f.variable("a")) is stored as a literal with negative phase.

The main developers of LogicNG all have their PhDs in Automated Reasoning and SAT Solving - therefore we naturally stick to the terminology mainly used in our field.

But let’s not discuss about syntax - we will add a comment in the next version of LogicNG to clarify things.

[koppor]

In this case, compatibility is the code comment compatbilitiy. It is still binary compatible.

I think, it would help to add some more description (JavaDoc) on it. Maybe just putting the synonmy there and a little usage example.

I used the library in my context as programmer. I was expecting the library building an AST similar to or(not(a), b) - thus not being a function. With the current API, it feels more like or((a, negated), (b, not negated)), which is strange for me.

I am not sure about your target user group. In University of Stuttgart teaching and research I never heared “phase”. But I only leanred logics, theoretical computer science, petri nets, model checking (Javier Esparza), published papers applying Prolog and an LTL solver (LoLa). I also liked CTL very much. Seems to be a different group of researchers than the ones involved in LogicNG. Not sure whether I am a target group and whether there are others with a similar background wanting to use LogicNG.

Since I assume there are other users around there who might be confused by phase, I am proposing to add more JavaDoc. I would even suggest to comment extensively as outlined in Java by Comparison. - If it is “only” at the construction of literals, it would be fine for me. For me, this was really the hardest part of the library up to now.