2022-11-22
==========
-You've renamed the GraphType.SubGraph enum to GraphType.SubordinationGraph, but not all partitions are subordinated graphs. Probably should keep this as SubGraph?
-ITimeMLLink.getID() is an integer, while other getID() methods are Strings. Should we make consistent?
-ITimeMLGraph has both removeX and removeXbyId methods. Do we need both?
-ITimeMLGraph: Do we want addAllX methods in addition to addX methods
-Rename ITimeMLNode.IType to ITimeMLNode.INodeType ?
-TimeMLSubGraph is defined too narrowly: you might want subgraphs with S-links
-Did we decided to have the connection between ITimeMLEvent and instance IDs captured in the graph, not the ITimeMLEvent object?
-ITimeMLInstance.getEvent() -> rename to .getEventID(); same with getSignal() -> getSignalID()
-TimeMLInstance: still takes an ITimeMLEvent in the constructor; should only be the id?
-Similarly with ITimeMLText.getRelatedInstances(): is this necessary?
-ITimeMLLink is still taking node objects and not ids
-Move ITimeMLText + impl to the .io package
-ITimeMLText should have Lists instead of Sets
-ITimeMLGraph to TCSP logic is in the TimeMLGraphTCSP constructor. This should be separated into a ITransformer + impl class
-We need to get the classes in the .timeline package to look more like the definitions in the paper. Please review.


2022-10-10
==========
-Rename all getId() methods as getID()
-getId() vs. getIdStr(): The javadoc says "Each xxx has to be identified by a unique ID number and String." Is this a part of the TimeML specification? If not, then perhaps would be best to remove getIdStr() and just use getID():String.
-ITimeMLEvent: getInstances() returns a set of Integers, but should they be Strings? cf. discussion above
-ITimeMLEvent: This still object involves a link to an ITimeMLInstance object. Is there a particular reason this connection should be made at the object level rather than through a data structured stored on the ITimeMLGraph? ITimeMLText has a getRelatedInstances() method, is that redundant?
-Same question for ITimeMLLink and its relationship to ITimeMLSignal
-ITimeMLLinkType.Origintype: Doesn't follow Java naming conventions. Also Javadoc for this inner class is inconsistent with implementation (2 or 3 types?)
-TimeMLLink: Something is funny with the parameterization of the Class parameter. What is stopping you from passing any Class object, e.g., Class<String> or Class<Integer>?
-TimeMLLink.getRelType() : Rename to getLinkType()?
-TimeMLLink.hashCode() and .equals() are not consistent with each other. Please check this for all classes.
-TimeMLText.checkArguments() throws an exception if you have no Timexes or Events or Links but this is perfectly possible. It also doesn't check that rawText and text are consistent with each other. 
-Do the methods other than parse(InputStream) : ITimeMLText need to be exposed on the interface?
-ITimeMLGraph.subGraph() should probably take ids, rather than objects
-ITimeMLGraph.getLinkTypesCount() has a problem with parameterization
-Rename IPartitionResult to IPartioning. Probably also want to add a getTimeMLGraph() method to retrieve the graph that has been partitioned
-PartitionResult doesn't check its arguments; these might not actually form a proper partition
-After running the JUnit tests, additional files appear that SVN is trying to check into the repo. JUnit test runs should have no side effects on the committed code.

2022-09-05
==========
-Rename edu.fiu.jtlex.processors to "..algorithms"
-Create new package edu.fiu.jtlex.graph; Move the following into it:
--IPartitionResult + impl
--ITimeMLGraph + impl
--ItimeMLGraphTCSP + impl
--ITimeMLNode
-Create a new package edut.fiu.jtlex.timeline; move the following into it:
--ITimeMLIndeterimancy + impl
--ITimeMLTimeline + impl
-edu.fiu.jtlex.data.Utils has only one method in it, relating to GraphType object. Eliminate this method and just use the GraphType.name() in TimeMLGraph.toString() method
-Move ITimeMLLinkType inside of ITimeMLLink
-Move IType inside of ITimeMLNode
-Instead of using LinkTag enum, why not just return the class of the ITimeMLLinkType object? Then you can eliminate the LinkType enum.
-Some classes have toJson(), and others have toJSON(). Pick one and do a search/replace to make consistent.
-The following interfaces/classes have direct links to other complete TimeML objects; these should reference to ID integers or strings, rather than objects:
--ITimeMLEvent + impl
--ITimeMLInstance + impl
--ITimeMLInstance + impl
-TimeMLParser: in various methods this class loops over the Sets to find objects with corresponding ids; you should use HashMaps for this (i.e., map id to object to retrieval is O(1))
-What happens if the event definition comes after the instance definition in the file? Is that allowed? Will the parser fail?


2022-07-29
==========
Note: Items marked with ** are from previous batches of comments

User Manual
-----------
**Unpack "JTLEX_users_manual.zip into "src" subfolder under "man" folder
**Rename "JTLEX User Manual.pdf" to "manual.pdf", "userguide.pdf", or something similar
-Set up TeXlipse project appropriately
-Figure out how to use TeXlipse (i.e., read the documentation)

Compiled Artifacts
------------------
**Where are the compiled libraries? See JWI for artifacts to be compiled and naming conventions. There should be several different artifacts in ver/1.0.0
 

2022-07-17
==========

User Manual
-Rename "User Manual" folder to "man"
-Unpack "JTLEX_users_manual.zip into "man" folder, or maybe "src" subfolder 
-Rename "JTLEX User Manual.pdf" to "manual.pdf", "userguide.pdf", or something similar
-See if you can figure out how to make this TeXlipse project as well, so the man file can be compiled from within Eclipse

Compiled Artifacts
-Where are the compiled libraries? See JWI for artifacts to be compiled and naming conventions
-Make a "ver" folder in the root, with subfolders corresponding to version numbers, e.g., "1.0.0", with compiled artifacts inside, with JWI-style artifact naming

-Let's do one major class at a time and see if we can keep up a rapid rhythym (one week turn around, say)

ITimeMLGraph
-addLink : what happens if the link is non-null, but the nodes are not in the graph? It should throw an IllegalArgumentException probably.
-Do you need a .removeLinkById method as well? You have a .removeNodeById method
-For removeLink/Node methods, it would make more sense to return a boolean, like Set.remove(Object)
-For removeNode, what happens if you remove a node that has links attached? Are the links also removed? I would suggest so.
-for getNodes() and getLinks(), you should specify more information about the sets returned. Are they internal data structures? If you call the method multiple times, do you always get the same exact object (cf. Java Hashmap.KeySet object and .keySet() method) If you modify the set, does it change anything about the original graph? There are at least two options here:
--Return an immutable wrapper around an internal data structure. 
--Return a modifiable set where removing/adding nodes to/from the set has the same semantics as the addNode/removeNode methods.
-I don't understand what getOutLinks() and getInLinks() do. the documentation doesn't explain well. What's the String for? What's the definition of In/Out links?
-getLinkTypesCount() : This method should be moved to a utility method, or made static on the interface, taking an ITimeMLGraph as an argument. Also the returned map should be a map from ITimeMLLinkType to Integers. 
-setGraphType(GraphType) still doesn't make sense to me. The GraphType derives from how the object was created, not what someone has called on this method. The getGraphType() should return an object that is computed from the state of the object. For example, what happens when you have a MainSubGraph, but then you add enough nodes to another 
-Given the above, I think GraphType needs to be reworked. Take a look at List.subList and it's various implementation. When you get a sublist, it is a "view" into the original list. When you modify the sublist, it modifies the bigger list. So I think it would make sense to have a subGraph(...) method, which allows you to pull out some portion of the bigger graph and all it's associated edges. You could then have a .isSubGraph():boolean method, maybe also a getParent():ITimeMLGraph method. Maybe also a
-Be more specific about how the .clone() method works. Are objects in the graph cloned?
-Should .toJson be named .toJSON ? There is probably a convention that people follow on this one.


2022-04-18
==========
-Rename IGraph to ITimeMLGraph?
-Rename INode to ITimeMLNode?
-Rename ILink to ITimeMLLink?
-Rename IText to ITimeMLText?
-Similar renamings for implementations?

-Methods in IGraph (and elsewhere) lack clarity on their semantics. For every method in every interface, answer the the following questions for every argument:
--What happens if you pass null? If it throws a NullPointerException, add a @throws NullPointerException to the javadoc with an explanation. If not, explain what null means.
--What happens if the input is not as expected? If it throws an IllegalArgumentException, add a @throws IllegalArgumentException to the javadoc, with a detailed explanation
--If the argument is a String, what happens if you pass an empty or a string with whitepace?

-IGraph.addLink: What happens if you add a link to the graph but the source and/or target node are not in the graph?
 
-IGraph.containsLink(): this is redundant with IGraph.getLinks().contains().

-IGraph.getLinksCount() and .getNodesCount() are redundant with IGraph.getLinks().size() and IGraph.getNodes().size().

-What happens if I call IGraph.getLinks()/.getNodes() and then manipulate that set directly? Is the set immuatable? Does it change the underlying graph? If the latter, how do you ensure in your implementations that internal data structures of IGraph are updated correctly?

-IGraph.setGraphType: It is unclear to me why you would need this exposed to users of the interface. What happens if you set the wrong graph type? Isn't a graph's type a function of how it was created and so shouldn't change?

-Should GraphType be a member of IGraph? Akin to IEvent.EventClass? Same question about ILinkType...should it be inside of ILink?

-IGraph.clone() says it provides a "deep copy" but Cloneable says "a field-by-field copy"

-Graph implementation takes File, String, or InputStream. I think it would make sense to break this logic into two parts: A GraphReader(?) or similar file that takes a stream (perhaps generated from a file or String) and makes a graph, and the Graph implementation which takes nodes and links, or another graph, as arguments to the constructors. 

-Graph.hashCode() is incorrect; it uses a sequential hashing function (Objects.hash) rather than a set-based hashing function (see AbstractSet.hashCode()). 

-Graph.equals() will not work if you pass in a different implementation of IGraph that is not a subclass of Graph. This does not seem to be the correct behavior.

-@since tags should reference a major or minor library version (e.g., jTLEX 1.0), not a repository revision

-You can easily go from IInstance objects to the IEvent, but not from an IEvent to all the related IInstance objects. Should there be a method IEvent.getInstances()?

-ITSCP has implementation GraphTSCP. Does this mean there are non-graph implementations of TSCPs?

-GraphTCSP doesn't seem to add much value on top of a Store object except the _timepoints field. Is there some reason why Store.vars does not provide the same functionality? If it doesn't add much, can we just eliminate this class? Perhaps this class can be used to maintain correspondences between specific IntVar objects and TimeML objects? Where are such correspondences kept, anyway?

-Further, GraphTSCP provides direct access to the _timepoints array. What happens if a caller changes the array?

-ITimeline seems to be a trunk-and-branch timeline structure, not a simple timeline. There should be two separate data structures.

-edu.fiu.jtlex.processes.Utils is essentially a test class, should be in the test folder. Same for Watch class.

-I wonder if you want to create a package edu.fiu.jtlex.timeml, and put all the timeml classes in there, namely: IGraph, ILink, INode, IEvent, ITimex, ISignal, IInstance, IText, etc. and implementations? For example:
edu.fiu.jtlex
  .timeml 
    .data -> all timeml data objects
    .io -> timeml file parser / writer
	
-ITimex/Timex and IInstance/Instance keep track of their in/out links. This is a function for the IGraph class. 

-No equals() methods implemented on Event, Timex, Instance, or  classes?

-As I recall, one of DURING or INCLUDES requires one of the related objects to be a time. Where is this enforced in the library?


2022-03-22
==========
-The Timeline for a graph is still a field on the graph itself. It should be separated. Similarly, the partitioner, indetermiancies, inconsistencies, suggested links, etc. are still stored in the IGraph object. These are processes that operate over IGraphs, can be computed multiple different ways and result in multiple different types of outputs. They should be moved elsewhere, probably in the TLEX class. IGraph should be a data structure that is independent of the complex operations computed over it.

-Package structure is still flat. Create at least two subpackages: edu.fiu.jtlex.data and edu.fiu.jtlex.processors. Move everything used in IGraph into data. Ideally anything in the data package will not import anything else in jtlex. modules that partition, detect indeterminacy or inconsistency can go in the processors package. Depending on how many additional top-levle classes each of those processors involves, you may way a special package. 

-In the root package, provide a main entry point to the library in the form of a class called TLEXAlgorithm.java or TLEX.java, along with its corresponding interface. It can be a singleton class but subclassable. This should have a single method that takes as input TimeML and outputs the final 

-Where is the datastructure corresponding to a trunk-and-branch timeline structure? 

-Where is the datastructure corresponding to an Indeterminacy Map?

-The IIndeterimancy interface doesn't seem to be used anywhere

-The IDisconnectivity and Disconnectivity classes are misnamed, as they seem to be processes rather than data. Also seems to be a mixed collection of disconnectivity related activities. So this should either be a class with static methods like Collections, or a class with standard process implementations named something like DisconnectivityProcessor that can be extended.

-The Javadoc for nearly all the methods I looked at don't answer basic questions about the semantics of the methods. Javadocs should answer at least the following questions:
--Does this method ever return null?
--What happens if you pass null to the method? (Usually NullPointerException, which should be annotated with @throws)
--In what version of the library was this method introduced? Cf. @since tag
--For methods that return numbers, what is the range of the numbers? Might they be zero or negative? Are they bounded?
--For methods that take collections, what happens if the collection is empty or immuatable? Consider @throws IllegalArgumentException to react to inappropriate empty collections passed as arguments
--For methods that return collections, might the collection be empty? Can the collection be changed? Is the collection an internal datastructure? If so, what happens if you change it?
--For objects in general, are they mutable or immutable? If mutable, does an immutable version exist? If so, how does one create it (cf. Collections.unmodifiableXXX methods)

-InconsistencyDetector and IndeterminancyDetector don't have governing interfaces.

-For GraphTCSP, the data and the process are still conflated. Separate out the structure of the TCSP from the class that solves the TCSP. Further, the object does not seem to permit access to the structure of the TCSP.

-The IGraphTCSP interface makes specific reference to JaCoP. Interfaces should not specify implementation details. In  general in the javadocs of interfaces there are numerous references to how the interface should be implemented. E.g., in IGraph it says "A graph is represented with two Hash Tables, one for Nodes and one for Links." This is not appropriate for an interface, these are implementation details that should be included in the relevant implementation class. 

-In Graph, why keep a separate record of number of links and nodes? Why not just use the size of the backing hash maps? Why do you need separate equalNodes() and equalLinks(), why does not just using equals() work? 

-In IGraph, why does hasSelfLoops return Boolean instead of boolean? Why does IGraph specify ArrayList instead of List as the return type? Why does getTimeline() return Timeline instead of ITimeline? Remember to program to interfaces, not implementations.

-I find that notating the "type" of the graph using an enum to be strange. Do you really need this?


